1-Mar-1998 21:49:05-GMT,3114;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 OAA07528 for ; Sun, 1 Mar 1998 14:49:03 -0700 (MST) 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, 01 Mar 1998 15:44:17 EST Received: from localhost (ajh@localhost) by indy03.cs.monash.edu.au (8.7.6/8.6.9) with SMTP id IAA08804; Mon, 2 Mar 1998 08:44:11 +1100 (EST) Message-ID: <199803012144.IAA08804@indy03.cs.monash.edu.au> To: LitProg@SHSU.edu, leew@samson.kean.edu Subject: Re: Literate programming class style? MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Date: Mon, 02 Mar 1998 08:44:09 +1100 From: John Hurst Reply-To: LitProg@SHSU.edu, ajh@cs.monash.edu.au Lee's paper is "Using Literate Programming Notation in Introductory Programming Courses", First Australasian Conference on Computer Science Education, pp267-72, Jul 1996. (published by ACM, Order no. 457963) On 26 Feb at 16:33, you wrote: > On 25 Feb 1998, Piet Tutelaers wrote: > > Does somebody have any experience with literate programming in > > combination with a programming class? It seems natural to do this in > > HTML so that one has the possibility to click on a <> > > with the result that the details of this piece are exploded. Another > > click on the <> target and the details disappear. > > > > before the click after the click > > > > ...... ....... > > <>; <>; > > ...... expansion lines > > for piece of code > > ....... > > > > While I haven't done exactly that, I *have* use LP (noweb) notation in > class to better teach top-down design and step-wise refinement. I > presented a paper on this at the First Australasian Conference on > Computer Science Education. I'm at the SIGCSE Conference in Atlanta > at the momemnt, so I don't have the exact citation for you. > > -- 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 | > ------------------------------------------------------------------------ --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 2-Mar-1998 0:56:10-GMT,2333;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 RAA11011 for ; Sun, 1 Mar 1998 17:56:08 -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; Sun, 01 Mar 1998 18:52:08 EST From: doyaaron@aol.com (Doyaaron) Reply-To: LitProg@SHSU.edu, doyaaron@aol.com Subject: CAN YOU PLEASE HELP ME ! Date: 2 Mar 1998 00:50:31 GMT Message-ID: <19980302005000.TAA20031@ladder03.news.aol.com> To: LitProg@SHSU.edu >From : doyaaron@aol.com Date : 03/01/98 Dear Friends, I, Terry need some help from you regarding HTML.I am totally new to HTML and I am trying to create my own on the web page through HTML help. Now, I am not able to put blank spaces in my line i.e Suppose I want NAME ITEM their should be 20 spaces between name & item, but i am not able to figure it out that how do i put those blank spaces.I tried a lot in different types but it ignores any blank spaces.I am using ActiveX Pad and AOL edit page editors.How much space i keep between both of them it ignores them.Can you please tell me which tag to use to display my space between NAME & ITEM. I am also not able to align my three paragraghs in same column using BLOCKQUOTE tag. Suppose, HEADING ( using H3 tag) BLOCKQUOTE> SUB HEADING 1 TITLE
  • TEXT
  • TEXT
  • TEXT
    • SUB HEADING 2 ... ..Same as Above ...
    SUB HEADING 3 ... ... ...
    Now, as using BLOCKQUOTE all my paragraghs should be in same column but they are as 1 para 2 para 3 para I also tried putting all the 3 para's ina single BLOCKQUOTE and using
    for new line, but also didn't worked. Can anyone please tell me how do i fix my this two problems:- 1) Something that can accept blank spaces 2) Something that can keep my three paragraph's in same column. I would be very glad if you can help me.Any sort of help is appreciated. Thank You Terry 2-Mar-1998 0:57:15-GMT,1388;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 RAA11059 for ; Sun, 1 Mar 1998 17:57:14 -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; Sun, 01 Mar 1998 18:52:06 EST From: Diego Zamboni Reply-To: LitProg@SHSU.edu, zamboni@cs.purdue.edu Subject: Re: pretty-printing with noweb Date: 2 Mar 1998 00:35:02 GMT Message-ID: <6dcurm$7qj$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 "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 2-Mar-1998 15:54:06-GMT,3105;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 IAA29691 for ; Mon, 2 Mar 1998 08:54:05 -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; Mon, 02 Mar 1998 09:24:42 EST From: Marc van Leeuwen Reply-To: LitProg@SHSU.edu, maavl@zenon.univ-poitiers.fr Subject: Re: Book-style CWEB output? Date: 2 Mar 1998 14:41:52 GMT Message-ID: <6degfg$rk8$1@murdoch.acc.Virginia.EDU> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit To: LitProg@SHSU.edu Jason Alexander wrote: > > Does anyone know if it is possible to easily get book-style output > (i.e., with chapters, table of contents, and the index at the end) from > Cweave? > > If so, does this require rewriting parts of the TeX input file used by > the generated TeX file, or does it require a different version of the > Cweave executable? It is not possible to automatically get such output, i.e., without designing the format yourself. Note however that you do get a table of contents and an index standard from cweave, and you may consider the division produced by "starred sections" (from '@*') as a division into chapters; you can insert a "level" number following the '@*' to indicate sections, subsections etcetera (there is even a level |-1| for a division that is coarser than the standard starred section). So I think I may interpret your question as whether it is possible to change the appearence of these features to make the result look more like a book. To that end you need to rewrite some macros defined in cwebmac.tex (I presume this is what you meant by "the TeX input file used by the generated TeX file"), and possibly add some new ones; this is what I meant by "designing the format yourself". It is not particularly easy, as some of the macros in cwebmac.tex are a bit tricky, but if you take some time to study what TeX normally does with the output of cweave, it is certainly doable. In any case there should be no need to change cweave, since it already provides the necessary clues the a format needs. It is even possible to arrange that the output of several runs of cweave be combined to a single TeX document, as the contributions to the index and table of contents are written to separate files, and they can be processed in other ways that simply running TeX on them. Of course this may require some more rewriting of macros, for instance to ignore or modify the section numbers that cweave writes explicitly to the TeX file. In my biased opinion you would do good to use my version CWEBx instead of CWEB (unless you are writing C++) if you are planning to do major rewriting, since it has several adaptations to improve flexibility of use, and documentation of the macros used. -- Marc van Leeuwen Universite de Poitiers http://wallis.univ-poitiers.fr/~maavl/ 2-Mar-1998 16:35:39-GMT,3105;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 JAA00896 for ; Mon, 2 Mar 1998 09:35:38 -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; Mon, 02 Mar 1998 09:24:48 EST From: Marc van Leeuwen Reply-To: LitProg@SHSU.edu, maavl@zenon.univ-poitiers.fr Subject: Re: Book-style CWEB output? Date: 2 Mar 1998 14:43:58 GMT Message-ID: <6degje$rqq$1@murdoch.acc.Virginia.EDU> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit To: LitProg@SHSU.edu Jason Alexander wrote: > > Does anyone know if it is possible to easily get book-style output > (i.e., with chapters, table of contents, and the index at the end) from > Cweave? > > If so, does this require rewriting parts of the TeX input file used by > the generated TeX file, or does it require a different version of the > Cweave executable? It is not possible to automatically get such output, i.e., without designing the format yourself. Note however that you do get a table of contents and an index standard from cweave, and you may consider the division produced by "starred sections" (from '@*') as a division into chapters; you can insert a "level" number following the '@*' to indicate sections, subsections etcetera (there is even a level |-1| for a division that is coarser than the standard starred section). So I think I may interpret your question as whether it is possible to change the appearence of these features to make the result look more like a book. To that end you need to rewrite some macros defined in cwebmac.tex (I presume this is what you meant by "the TeX input file used by the generated TeX file"), and possibly add some new ones; this is what I meant by "designing the format yourself". It is not particularly easy, as some of the macros in cwebmac.tex are a bit tricky, but if you take some time to study what TeX normally does with the output of cweave, it is certainly doable. In any case there should be no need to change cweave, since it already provides the necessary clues the a format needs. It is even possible to arrange that the output of several runs of cweave be combined to a single TeX document, as the contributions to the index and table of contents are written to separate files, and they can be processed in other ways that simply running TeX on them. Of course this may require some more rewriting of macros, for instance to ignore or modify the section numbers that cweave writes explicitly to the TeX file. In my biased opinion you would do good to use my version CWEBx instead of CWEB (unless you are writing C++) if you are planning to do major rewriting, since it has several adaptations to improve flexibility of use, and documentation of the macros used. -- Marc van Leeuwen Universite de Poitiers http://wallis.univ-poitiers.fr/~maavl/ 2-Mar-1998 23:20:25-GMT,2208;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 QAA12831 for ; Mon, 2 Mar 1998 16:20: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; Mon, 02 Mar 1998 17:12:37 EST From: postmaster@127.0.0.1 (Benoit Goudreault-Emond) Subject: Re: Book-style CWEB output? Date: 2 Mar 1998 23:08:59 GMT Message-ID: <6dfe6b$pje$1@elna.ethz.ch> Reply-To: LitProg@SHSU.edu, postmaster@127.0.0.1 To: LitProg@SHSU.edu In article <6degfg$rk8$1@murdoch.acc.Virginia.EDU>, Marc van Leeuwen wrote: > > Does anyone know if it is possible to easily get book-style output > > (i.e., with chapters, table of contents, and the index at the end) from > > Cweave? > > It is not possible to automatically get such output, i.e., without > designing the format yourself. Note however that you do get a table of [snip] Actually, although it is not, strictly speaking, a TeX solution, Joachim Scrhod built a package to use cweave with LaTeX. The LaTeX table of contents, index, etc. are available, as the thing is an almost standard LaTeX document. It's supposed to be available on CTAN in macros/latex/contrib/supported/cweb/. It's also at ftp://ftp.th-darmstadt.de/pub/programming/literate-programming/c.c++ as cweb-sty-.tar.gz [UNVERIFIED]. There is a slight problem with the latest cweb. There is a patch available in the Debian Linux distribution, so you can pick up the original tar and the patch at ftp.debian.org, apply the patch and then build normally. Granted, this is not exactly an answer, as it's not a strictly TeX solution, but it does provide a book-style output. -- Benoit Goudreault-Emond -- Student, Computer Engineering, Concordia University ``Being too close to a fireball can worry a man --- to death.'' -- Zeb Carter in "The Number of the Beast" by Robert A. Heinlein Note: the "From:" address is not correct to protect myself against spam. My actual e-mail address is: ``bgoudem AT axess DOT com'' 3-Mar-1998 0:12:21-GMT,1097;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 RAA14251 for ; Mon, 2 Mar 1998 17:12:20 -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; Mon, 02 Mar 1998 18:06:03 EST From: "Giovanni Siano" Reply-To: LitProg@SHSU.edu, gsiano@edl.it Subject: Re: #Line directive Date: 2 Mar 1998 23:58:18 GMT Message-ID: <6dfh2q$ion$1@murdoch.acc.Virginia.EDU> To: LitProg@SHSU.edu Thank you very much for your answer ... I hope that it'll be possible in the future to have this feature in Delphi .. Meanwhile it would be possible to work on a sort of preprocessor to preprocess the Delphi error file and litpro sources (e.g. a modified Funnelweb) containing special commented #line directive [I did this with Modula 2]) .... Let me know if you're interested on this kind of project ... Sincerly, Giovanni 3-Mar-1998 9:57:39-GMT,1914;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 CAA27195 for ; Tue, 3 Mar 1998 02:57:38 -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; Tue, 03 Mar 1998 03:43:41 EST From: Dan Schmidt Reply-To: LitProg@SHSU.edu, dfan@harmonixmusic.com Subject: Re: pretty-printing with noweb Date: 2 Mar 1998 17:39:13 GMT Message-ID: <6deqs1$57e$1@murdoch.acc.Virginia.EDU> To: LitProg@SHSU.edu Diego Zamboni writes: | "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. dpp is meant to work for C++ just as well as it does for C; please let me know if it doesn't. The extent of its pretty-printing may be more than what David wants. It tries to mimic CWEB style. I haven't had time to work on it recently, but I do fix bugs if they're reported. -- 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-Mar-1998 20:55:14-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 NAA13107 for ; Tue, 3 Mar 1998 13:55:11 -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; Tue, 03 Mar 1998 13:41:54 EST From: thompson@sun1.coe.ttu.edu Subject: comp.programming.literate FAQ Date: 3 Mar 1998 12:33:13 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-Mar-1998 20:53:36-GMT,1867;000000000001 Received: from plot79.math.utah.edu (beebe@plot79.math.utah.edu [128.110.198.3]) by csc-sun.math.utah.edu (8.8.5/8.8.5) with ESMTP id NAA13092; Tue, 3 Mar 1998 13:53:35 -0700 (MST) From: "Nelson H. F. Beebe" Received: (from beebe@localhost) by plot79.math.utah.edu (8.8.5/8.8.5) id NAA27110; Tue, 3 Mar 1998 13:53:34 -0700 (MST) Date: Tue, 3 Mar 1998 13:53:34 -0700 (MST) To: litprog@SHSU.edu Cc: beebe@math.utah.edu X-US-Mail: "Center for Scientific Computing, University of Utah, 155 S 1400 E RM 233, Salt Lake City, UT 84112-0090, USA" X-Telephone: +1 801 581 5254 X-FAX: +1 801 581 4148 X-URL: http://www.math.utah.edu/~beebe Subject: litprog.bib bibliography update Message-ID: I've just completed a major update to the literate programming bibliography at http://www.math.utah.edu/pub/tex/bib/index.html#litprog ftp://ftp.math.utah.edu/pub/tex/bib/index.html#litprog adding 35 new entries, following searches in some German libraries, and some U.S. databases. Contributions to this bibliography are always welcome; if you see a new publication on literate programming, or have written one, and don't find it covered there, please let me know about it. ---------------------------------------------------------------------------- - Nelson H. F. Beebe Tel: +1 801 581 5254 - - Center for Scientific Computing FAX: +1 801 581 4148 - - University of Utah Internet e-mail: beebe@math.utah.edu - - Department of Mathematics, 105 JWB beebe@acm.org - - 155 S 1400 E RM 233 beebe@ieee.org - - Salt Lake City, UT 84112-0090, USA URL: http://www.math.utah.edu/~beebe - ---------------------------------------------------------------------------- 3-Mar-1998 21:08:07-GMT,1151;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 OAA13475 for ; Tue, 3 Mar 1998 14:08:05 -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; Tue, 03 Mar 1998 14:56:10 EST From: cyberherp@aol.com (CyberHerp) Reply-To: LitProg@SHSU.edu, cyberherp@aol.com Subject: BOYCOTT MACMILLAN DIGITAL Date: 3 Mar 1998 20:50:08 GMT Message-ID: <19980303205000.PAA21865@ladder03.news.aol.com> To: LitProg@SHSU.edu Windows 3.x users like me are getting sick of being short changed just because we operate on a different operating system. I purchased a Visual basic programming kit from macmillan digital. I wasn't expecting everything that a windows 95 user gets, but I was at least expecting multiple window support! If you are a windows 3.x user and/or would like to help me in boycotting macmillan digital, please e-mail me at: Cyberherp@aol.com 3-Mar-1998 21:10:36-GMT,2178;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 OAA13547 for ; Tue, 3 Mar 1998 14:10:34 -0700 (MST) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from csc-sun.math.utah.edu by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Tue, 03 Mar 1998 14:53:37 EST Received: from plot79.math.utah.edu (beebe@plot79.math.utah.edu [128.110.198.3]) by csc-sun.math.utah.edu (8.8.5/8.8.5) with ESMTP id NAA13092; Tue, 3 Mar 1998 13:53:35 -0700 (MST) From: "Nelson H. F. Beebe" Reply-To: LitProg@SHSU.edu, beebe@math.utah.edu Received: (from beebe@localhost) by plot79.math.utah.edu (8.8.5/8.8.5) id NAA27110; Tue, 3 Mar 1998 13:53:34 -0700 (MST) Date: Tue, 3 Mar 1998 13:53:34 -0700 (MST) To: litprog@SHSU.edu CC: beebe@math.utah.edu Subject: litprog.bib bibliography update Message-ID: I've just completed a major update to the literate programming bibliography at http://www.math.utah.edu/pub/tex/bib/index.html#litprog ftp://ftp.math.utah.edu/pub/tex/bib/index.html#litprog adding 35 new entries, following searches in some German libraries, and some U.S. databases. Contributions to this bibliography are always welcome; if you see a new publication on literate programming, or have written one, and don't find it covered there, please let me know about it. ---------------------------------------------------------------------------- - Nelson H. F. Beebe Tel: +1 801 581 5254 - - Center for Scientific Computing FAX: +1 801 581 4148 - - University of Utah Internet e-mail: beebe@math.utah.edu - - Department of Mathematics, 105 JWB beebe@acm.org - - 155 S 1400 E RM 233 beebe@ieee.org - - Salt Lake City, UT 84112-0090, USA URL: http://www.math.utah.edu/~beebe - ---------------------------------------------------------------------------- 4-Mar-1998 10:38:19-GMT,2027;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 DAA03009 for ; Wed, 4 Mar 1998 03:38:19 -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, 04 Mar 1998 04:25:25 EST From: Lee Wittenberg Reply-To: LitProg@SHSU.edu, leew@samson.kean.edu Subject: Re: #Line directive Date: 2 Mar 1998 16:29:59 GMT Message-ID: <6demq7$2ff$1@murdoch.acc.Virginia.EDU> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII To: LitProg@SHSU.edu On 27 Feb 1998, Giovanni Siano wrote: > I'd like to use a literate programming tool with Delphi > > Does anybody know how to emulate in Delphi the #LINE and #FILE directives of > C-languages? In Delphi 2.0, there is no way to do this. I haven't had a chance to look at 3.0, but I'd be willing to bet that it doesn't. I've talked to some Borland folks about this, and they passed on my requests (both for #line/file's and allowing preprocessing tools), but I doubt that it was a high priority. On the other hand, I have the email address of a Borland rep I spoke to at SIGCSE last week. I'll forward your request to her. -- Lee P.S. I find it kind of interesting that #line/file, which were only invented to support the C preprocessor, have turned out to be so utterly useful other contexts. In fact, I would say that, aside from the #if's, they are the most useful construct. ------------------------------------------------------------------------ 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-Mar-1998 17:53:38-GMT,1894;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 KAA13041 for ; Wed, 4 Mar 1998 10:53:34 -0700 (MST) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from ns.imgmail.com by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Wed, 04 Mar 1998 11:10:20 EST Received: from localhost (davell@localhost) by ns.imgmail.com (8.8.6/8.8.6) with SMTP id MAA04744; Wed, 4 Mar 1998 12:09:10 -0500 Date: Wed, 4 Mar 1998 12:09:10 -0500 From: Davell Trading Received: by ns.imgmail.com (bulk_mailer v1.5); Wed, 4 Mar 1998 10:26:51 -0500 To: davell@imgmail.com Reply-To: LitProg@SHSU.edu, davell@imgmail.com Subject: Learn the Lazy Person's Secret to Overnight Wealth! Message-ID: With nothing more than the information in this dynamic report, you can increase your income within a few short days. This is not a shady MLM, but a source of valuable "how-to" information indispensable to the entrepreneurial information seeker. Please visit our information-packed web site to view a listing of our reports. If you act now - the Lazy Person's Secret will be yours for as low as $5.95! Come check us out right now! Come and find all of the information you've ever wanted but didn't know where to look! http://www.davell-trading.com http://www.davell-trading.com _______________________________________________________________________ Davell Trading respects your online time and Internet privacy. This is a one-time only solicitation. Your address will be deleted from our files. Thank you! _______________________________________________________________________ 5-Mar-1998 17:40:18-GMT,1526;000000000001 Received: from tsai2.tsai.es (tsai2DMZ.tsai.es [194.179.46.130]) by csc-sun.math.utah.edu (8.8.5/8.8.5) with ESMTP id KAA18096 for ; Thu, 5 Mar 1998 10:40:16 -0700 (MST) Received: from srvcomm.fihoca.int ([194.224.52.214]) by tsai2.tsai.es (Netscape Mail Server v1.1) with ESMTP id AAA6967 for ; Thu, 5 Mar 1998 18:40:58 +0200 Received: from PCJOSEPV_W95.fihoca.int by srvcomm.fihoca.int with SMTP (Microsoft Exchange Internet Mail Service Version 5.0.1460.8) id GFS1HWRH; Thu, 5 Mar 1998 18:38:24 +0100 Message-ID: <34FEE2E4.CCACB7C7@fihoca.com> Date: Thu, 05 Mar 1998 18:37:40 +0100 From: Josep Vela Organization: grup FIHOCA X-Mailer: Mozilla 4.04 [en] (Win95; I) MIME-Version: 1.0 To: "Nelson H. F. Beebe" Subject: Re: Literate programming with SGML References: Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit Thanks for your info. I forward the request for the two references to the British Library Iinternational photocopy service in order to obtain a printed copy. Btw, the reference from D.Morales-German is a bit older B-), maybe nobody is using SGML for merge doc, data and code and do literate programming. May ask you about what you think of that? Thanks in advance for your time. -- Josep Vela - R&D Manager grup FIHOCA Avda. Roma, 25 08029 Barcelona - Spain Phone: +34 3 410 90 00 - Fax: +34 3 410 30 81 6-Mar-1998 20:16:07-GMT,1169;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 NAA26015 for ; Fri, 6 Mar 1998 13:15:55 -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, 06 Mar 1998 13:41:37 EST From: Robert Lopez Reply-To: LitProg@SHSU.edu, Robert.Lopez@abq.sc.philips.com Subject: Literate Perl? Date: 06 Mar 1998 12:32:08 -0700 Message-ID: To: LitProg@SHSU.edu In the past I have used cnoweb to document a couple of projects. Now I am starting a large perl project and I would like to use TeX/WEB for documentation rather than the perl POD (Plain Old Documentation). Is anyone doing this? Are there any tools to support this? -- Robert Lopez Philips Semiconductors, 9201 Pan American Fwy. N.E., ms 20, Albuquerque, New Mexico 87113 USA [P: (505)822-7112 F: ...7237] 7-Mar-1998 18:05:12-GMT,1595;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 LAA27318 for ; Sat, 7 Mar 1998 11:05:11 -0700 (MST) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from gummy.cs.indiana.edu by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Sat, 07 Mar 1998 11:57:34 EST Received: (from wdueber@localhost) by gummy.cs.indiana.edu (8.8.7/8.8.7/IUCS_2.16) id MAA08785; Sat, 7 Mar 1998 12:57:31 -0500 (EST) Date: Sat, 7 Mar 1998 12:57:31 -0500 (EST) From: Bill Dueber Reply-To: LitProg@SHSU.edu, wdueber@cs.indiana.edu Message-ID: <199803071757.MAA08785@gummy.cs.indiana.edu> To: LitProg@SHSU.edu, Robert.Lopez@abq.sc.philips.com Subject: Re: Literate Perl? In article <6drlkn$ioe$1@murdoch.acc.Virginia.EDU> you write: >In the past I have used cnoweb to document a couple of projects. >Now I am starting a large perl project and I would like to use TeX/WEB >for documentation rather than the perl POD (Plain Old Documentation). To the best of my knowledge, there's nothing specifically designed for Perl. I've used just regular noweb, though, with good results. Perl 5 and above does take a standard # LINE directive (although it's not well-documented), so you should be fine. Don't knock yourself out looking for a pretty-printer for Perl, though -- the language is ugly enough (i.e., flexible) that I can't imagine it's worth the effort. Good luck! -Bill- 7-Mar-1998 18:27:35-GMT,1988;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 LAA27756 for ; Sat, 7 Mar 1998 11:27:34 -0700 (MST) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from platon.ee.duth.gr by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Sat, 07 Mar 1998 12:16:56 EST Received: from localhost by platon.ee.duth.gr with SMTP (1.39.111.2/16.2) id AA060714257; Sat, 7 Mar 1998 20:10:57 +0200 Date: Sat, 7 Mar 1998 20:10:57 +0200 (EET) From: Apostolos Syropoulos Reply-To: LitProg@SHSU.edu, apostolo@platon.ee.duth.gr To: LitProg@SHSU.edu, Robert.Lopez@abq.sc.philips.com Subject: Re: Literate Perl? Message-ID: MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII On 6 Mar 1998, Robert Lopez wrote: > > In the past I have used cnoweb to document a couple of projects. > > Now I am starting a large perl project and I would like to use TeX/WEB > for documentation rather than the perl POD (Plain Old Documentation). > > Is anyone doing this? Are there any tools to support this? A few years ago while working with SpiderWEB I designed a pretty-printing grammar for Perl. Unfortunately the grammar couldn't cover all the keyword and/or function names. It worked, but I recommend you to use either noweb of nuweb instead. apostolos... **************************************************************** *Apostolos Syropoulos * *snail mail: 366, 28th October Str., GR-671 00 Xanthi, HELLAS * *email : apostolo@platon.ee.duth.gr * *phone num.: +30-(0)541-28704 * *home page : http://platon.ee.duth.gr/~apostolo * **************************************************************** 8-Mar-1998 9:24:24-GMT,1547;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 CAA12408 for ; Sun, 8 Mar 1998 02:24:23 -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; Sun, 08 Mar 1998 03:06:25 EST From: Lee Wittenberg Reply-To: LitProg@SHSU.edu, leew@samson.kean.edu Subject: Re: Literate Perl? Date: 7 Mar 1998 17:34:06 GMT Message-ID: <6ds0ee$n8r$1@murdoch.acc.Virginia.EDU> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII To: LitProg@SHSU.edu On 6 Mar 1998, Robert Lopez wrote: > > In the past I have used cnoweb to document a couple of projects. > > Now I am starting a large perl project and I would like to use TeX/WEB > for documentation rather than the perl POD (Plain Old Documentation). > > Is anyone doing this? Are there any tools to support this? noweb, nuweb, Funnelweb, or any of the language independents should do the job. -- 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-Mar-1998 20:13:16-GMT,1548;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 NAA22247 for ; Sun, 8 Mar 1998 13:13:15 -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; Sun, 08 Mar 1998 14:07:06 EST From: Andrew Johnson Reply-To: LitProg@SHSU.edu, ajohnson@gpu.srv.ualberta.ca Subject: Re: Literate Perl? Date: 8 Mar 1998 00:50:56 GMT Message-ID: <6dsq1g$41m$1@murdoch.acc.Virginia.EDU> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit To: LitProg@SHSU.edu Robert Lopez wrote: > > In the past I have used cnoweb to document a couple of projects. > > Now I am starting a large perl project and I would like to use TeX/WEB > for documentation rather than the perl POD (Plain Old Documentation). > > Is anyone doing this? Are there any tools to support this? I frequently use noweb with Perl...and, of course, it is not mutually exclusive with POD's--- pods can go in their own code-chunk so the user-docs are embedded in the tangled script... in fact, I've recently taken to using a pre-markup filter to strip out a pod chunk and replace it with its latex equivelant (using a slightly hacked-up version of perl's pod2latex utility) before passing off to the rest of the noweave pipeline for formatting. regards andrew 9-Mar-1998 1:16:06-GMT,1179;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 SAA27457 for ; Sun, 8 Mar 1998 18:16:04 -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; Sun, 08 Mar 1998 19:11:06 EST From: Robert Lopez Subject: Literate Perl? Date: 7 Mar 1998 14:29:42 GMT Message-ID: <6drlkn$ioe$1@murdoch.acc.Virginia.EDU> Reply-To: LitProg@SHSU.edu, LitProg@SHSU.edu, Robert.Lopez@abq.sc.philips.com To: LitProg@SHSU.edu In the past I have used cnoweb to document a couple of projects. Now I am starting a large perl project and I would like to use TeX/WEB for documentation rather than the perl POD (Plain Old Documentation). Is anyone doing this? Are there any tools to support this? -- Robert Lopez Philips Semiconductors, 9201 Pan American Fwy. N.E., ms 20, Albuquerque, New Mexico 87113 USA [P: (505)822-7112 F: ...7237] 9-Mar-1998 3:57:41-GMT,1489;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 UAA00146 for ; Sun, 8 Mar 1998 20:57:39 -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; Sun, 08 Mar 1998 21:53:46 EST From: Daniel Heck Reply-To: LitProg@SHSU.edu, daniel.heck@rhein-neckar.netsurf.de Subject: Re: modular literate programming Date: 6 Mar 1998 16:45:46 GMT Message-ID: <6dp97q$b5j$1@murdoch.acc.Virginia.EDU> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit To: LitProg@SHSU.edu David Martin wrote: > I am trying to find a way to do literate programming in a modular > manner, and have not found a satisfactory way to do so with noweb. The > noweb model seems to be that there is _one_ noweb file. This is clearly > not satisfactory. Putting multiple noweb files on the tangle > command-line is not general, and also not satisfacory. > > Am I missing an elegant solution for noweb? Or should I use nuweb, > which has an include directive? > LaTeX and C++ is my modus operandi, if that makes a difference... Did you ever take a look at CWEB? As far as I know, CWEB supports modular programming -- at least to some extend. > David Martin Daniel Heck 9-Mar-1998 5:00:54-GMT,3393;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 WAA01156 for ; Sun, 8 Mar 1998 22:00:53 -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; Sun, 08 Mar 1998 22:55:32 EST From: Rafael Laboissiere Reply-To: LitProg@SHSU.edu, rafael@dunite.icp.inpg.fr Subject: noweb and modularity Date: 6 Mar 1998 16:44:51 GMT Message-ID: <6dp963$b5b$1@murdoch.acc.Virginia.EDU> MIME-Version: 1.0 (generated by tm-edit 7.100) Content-Type: multipart/mixed; boundary="Multipart_Thu_Mar__5_19:47:04_1998-1" Content-Transfer-Encoding: 7bit To: LitProg@SHSU.edu --Multipart_Thu_Mar__5_19:47:04_1998-1 Content-Type: text/plain; charset=US-ASCII Hi, I ran into a problem when trying to use several files in a single noweb project. In my project, I have a LaTeX master file (say, doc.tex) that \include's three others: say, a.tex, b.tex, and copyright.tex. These later files are generated from a.nw, b.nw, and copyright.nw, respectively, using the command "noweave -n -index" I _really_ want to keep these noweb files separated. In the code chunks appearing in both a.nw and b.nw a copyright notice chunk (defined in copyright.nw) is included. Tangling works fine, provided that copyright.nw appears in the notangle command. Problems arise with noweave. Copyright chunks appear as "(never defined)" in a.tex and b.tex, what is obvious, because I cannot use copyright.nw for weaving a.nw or b.nw (otherwise the copyright notice chunk would appear several times in my printed document). I am clueless. Does somebody know how to solve this problem? The obvious solution for me problem is to come back to nuweb, which has a marvellous include directive (@i), but I am trying to stick to a better supported system (noweb). (I am attaching a .tar.gz file to this post. It contains the files a.nw, b.nw, copyright.nw, doc.tex of the example above, as well as a Makefile to show the noweb commands. Of course, this is a stripped-down illustration.) Rafael Laboissiere Institut de la Communication Parlee | Email: rafael@icp.inpg.fr UPRESS A CNRS 5009 / INPG | Voice: +33 4.76.57.48.49 46, av. Felix Viallet | Fax: +33 4.76.57.47.10 F-38031 Grenoble CEDEX 1 France | URL: http://www.icp.inpg.fr/~rafael --Multipart_Thu_Mar__5_19:47:04_1998-1 Content-Type: application/octet-stream; type=tar+gzip Content-Disposition: attachment; filename="noweb-problem.tar.gz" Content-Transfer-Encoding: base64 H4sIAOPw/jQAA+2XS0+DQBDHe3U/xSTWRA9t5FGwpJJqE29ePPeyLNNKikvDw9Y0/e7OIoXG RHuR+tr/gdmFYWZ5/IaB9+Wq07IuSY5tK2ub1qCcGwOntKUcs0MOrjtw1YT2G4ar/NtemFKR 5TyllCmfcYw/9ovE8tM41aXU9pforpAijxIJNx4bjXh/7fvXNJiKZPmSRvPH3PfZKYgkRJgl Kdyw8XevWOsrFfw0/k2j4t/U/B9BNf+3iv/gEP+3mv+/pfo5t1gHDvLvWjX/pqmOG9bANjT/ R9Bk9/xBJnkk0HsH/zXR3/icTy7AGA6v4B51IfgTChPRz3Hdao5D/JuXbsW/49qOpfg3S9vq qir9c/6n9AIUTyhzEfMs2/CUikCMWzYtMlxyseBz3MhkhQHtCnAeyc3uhC1j00iKuAhxw7fN ONgb14VEOZdhxGMhFxnNUIZ7ob77Nvxb3fMFzqIY28xxkH/LaPh37ZJ/x9L8H0Oqs/eA/vuB en/GzvprD86oF2Qn1A9wOY8Reg/dMXRHsN8qgg/dMWM7gLn6hfCg+phQOLUNym1zFs1UAjJN ihXyZ8ogoRfJkLwpzVtkXRG0tLS02tUrihmtLgAYAAA= --Multipart_Thu_Mar__5_19:47:04_1998-1-- 9-Mar-1998 7:23:57-GMT,4284;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 AAA03891 for ; Mon, 9 Mar 1998 00:23:56 -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; Mon, 09 Mar 1998 01:01:31 EST From: Norman Ramsey Reply-To: LitProg@SHSU.edu, nr@cs.virginia.edu Subject: Re: noweb and modularity Date: 6 Mar 1998 17:37:36 GMT Message-ID: <6dpc90$evg$1@murdoch.acc.Virginia.EDU> To: LitProg@SHSU.edu In article <6dp963$b5b$1@murdoch.acc.Virginia.EDU>, Rafael Laboissiere wrote: >I ran into a problem when trying to use several files in a single noweb >project. In my project, I have a LaTeX master file (say, doc.tex) that >\include's three others: say, a.tex, b.tex, and copyright.tex. These >later files are generated from a.nw, b.nw, and copyright.nw, >respectively, using the command "noweave -n -index" I _really_ want to >keep these noweb files separated. In the code chunks appearing in both >a.nw and b.nw a copyright notice chunk (defined in copyright.nw) is >included. > >Tangling works fine, provided that copyright.nw appears in the notangle >command. Problems arise with noweave. Copyright chunks appear as >"(never defined)" in a.tex and b.tex, what is obvious, because I cannot >use copyright.nw for weaving a.nw or b.nw (otherwise the copyright >notice chunk would appear several times in my printed document). > >I am clueless. Does somebody know how to solve this problem? The >obvious solution for me problem is to come back to nuweb, which has a >marvellous include directive (@i), but I am trying to stick to a better >supported system (noweb). I've add this to the noweb FAQ: A. This is a form of question that arises repeatedly, which is to say, ``what is the scope of chunk names?'' In Noweb, chunk names are in the same scope if the files in which the chunks appear are used on the same command line. Thus, the normal rule is one Noweb file per command line, and therefore each file is its own scope. You want to have chunks in the same scope for purposes of tangling, but not to weave files together. If you want files a.nw and b.nw in separate scopes, the situation is hopeless, because ``being in the same scope'' has to be a transitive property, and if a.nw and b.nw are both in the same scope as copyright.nw, they must be in the same scope as each other. However, if you want all files to be in the same scope, there is a solution, although it is a bit ugly. The solution is to weave all the files together, then use a special back end to split them into separate .tex files. This back end, called scopehack, could be used as follows: noweave -n -index -backend scopehack *.nw and this results in multiple *.tex files as required. And the fix, which is grotesque, is a short Icon program. # scopehack; a replacement for totex but splitting output into multiple files # -- to be used to weave all files in the same scope, but to separate .tex files global totex procedure main(args) totex := "PATH=/usr/local/noweb/lib:$PATH totex" # grotesque; must fix noweave to make this unnecessary every totex ||:= " '" || !args || "'" lines := [] file while line := read() do { line ? if ="@fatal" then exit(1) else if ="@file " then if =\file & pos(0) then # no change &null else { flush(file, lines) file := tab(0) } put(lines, line) } flush(file, lines) end procedure flush(file, lines) if /file & *lines > 0 then stop("First line is not @file") else if *lines = 0 then return else { outfile := suffex(file) || ".tex" p := open(totex || " > " || outfile, "wp") | stop ("cannot run ", totex) while write(p, get(lines)) close(p) return } end procedure suffex(s) return reverse (reverse(s) ? {tab(upto('.')) & ="."; tab(0)}) end 9-Mar-1998 17:55:24-GMT,1717;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 KAA15630 for ; Mon, 9 Mar 1998 10:55:21 -0700 (MST) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from ernie.ucop.edu by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Mon, 09 Mar 1998 11:34:48 EST Received: from carbon.ucop.edu (carbon.ucop.edu [128.48.108.116]) by ernie.ucop.edu (AIX4.2/UCB 8.7/8.7) with SMTP id JAA21624; Mon, 9 Mar 1998 09:34:43 -0800 (PST) Message-ID: <199803091734.JAA21624@ernie.ucop.edu> Date: Mon, 09 Mar 1998 09:35:39 -0800 From: Jerry.Wilcox@ucop.edu (Jerry Wilcox) Reply-To: LitProg@SHSU.edu, Jerry.Wilcox@ucop.edu To: LitProg@SHSU.edu, Robert.Lopez@abq.sc.philips.com Subject: Re: Literate Perl? References: <6drlkn$ioe$1@murdoch.acc.Virginia.EDU> (A copy of this message has also been posted to the following newsgroups: comp.programming.literate) In article <6drlkn$ioe$1@murdoch.acc.Virginia.EDU>, LitProg@SHSU.edu, Robert.Lopez@abq.sc.philips.com wrote: >Now I am starting a large perl project and I would like to use TeX/WEB >for documentation rather than the perl POD (Plain Old Documentation). > I use noweb to develop and document my perl. In fact, a lot of what I do is Sybperl, so the same noweb documents which describe and generate the perl also define the Sybase tables, etc, and generate the necessary SQL. Oh, and I can also include chunks for POD if desired. Highly Recommended! Jerry -- Jerry Wilcox == Jerry.Wilcox@ucop.edu I don't speak for the University and it doesn't speak for me. 9-Mar-1998 18:05:32-GMT,1325;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 LAA15913 for ; Mon, 9 Mar 1998 11: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; Mon, 09 Mar 1998 11:48:26 EST From: Jerry.Wilcox@ucop.edu (Jerry Wilcox) Reply-To: LitProg@SHSU.edu, Jerry.Wilcox@ucop.edu Subject: Re: Literate Perl? Date: 9 Mar 1998 17:39:25 GMT Message-ID: <6e19gd$eho$1@elna.ethz.ch> To: LitProg@SHSU.edu In article <6drlkn$ioe$1@murdoch.acc.Virginia.EDU>, LitProg@SHSU.edu, Robert.Lopez@abq.sc.philips.com wrote: >Now I am starting a large perl project and I would like to use TeX/WEB >for documentation rather than the perl POD (Plain Old Documentation). > I use noweb to develop and document my perl. In fact, a lot of what I do is Sybperl, so the same noweb documents which describe and generate the perl also define the Sybase tables, etc, and generate the necessary SQL. Oh, and I can also include chunks for POD if desired. Highly Recommended! Jerry -- Jerry Wilcox == Jerry.Wilcox@ucop.edu I don't speak for the University and it doesn't speak for me. 9-Mar-1998 20:37:58-GMT,3861;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 NAA19798 for ; Mon, 9 Mar 1998 13:37:57 -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; Mon, 09 Mar 1998 13:56:54 EST From: Robert Lopez Reply-To: LitProg@SHSU.edu, Robert.Lopez@abq.sc.philips.com Subject: Re: Literate Perl? Date: 09 Mar 1998 12:39:14 -0700 Message-ID: To: LitProg@SHSU.edu I (Robert Lopez ) wrote: > In the past I have used cnoweb to document a couple of > projects. Now I am starting a large perl project and I would > like to use TeX/WEB for documentation rather than the perl POD > (Plain Old Documentation). Is anyone doing this? Are there any > tools to support this? Thanks to Bill Dueber, Andrew Johnson, Apostolos Syropoulos, Jerry Wilcox and Lee Wittenberg for responding. >From the responses I have learned that there are some language independent tools: noweb, nuweb, and Funnelweb. There may be others. Any of these should be able to work with Perl. Some additional work may be required for particular end results. It is possible to combine POD and web documentation. I found that noweb has a home site at and some mention of Funnelweb. I found a site for Funnelweb at I found a collection that included noweb, nuweb and Funnelweb and similar tools at a CTAN mirror and I suppose they are all available at all CTAN sites. After the majority recommendation and overlooking the above sites I have decided to try to use noweb for my project. Thanks Everyone. -Robert Lopez Here are the responses I received: Bill Dueber : To the best of my knowledge, there's nothing specifically designed for Perl. I've used just regular noweb, though, with good results. Perl 5 and above does take a standard # LINE directive (although it's not well-documented), so you should be fine. Don't knock yourself out looking for a pretty-printer for Perl, though -- the language is ugly enough (i.e., flexible) that I can't imagine it's worth the effort. Andrew Johnson : A few years ago while working with SpiderWEB I designed a pretty-printing grammar for Perl. Unfortunately the grammar couldn't cover all the keyword and/or function names. It worked, but I recommend you to use either noweb of nuweb instead. Jerry Wilcox : I use noweb to develop and document my perl. In fact, a lot of what I do is Sybperl, so the same noweb documents which describe and generate the perl also define the Sybase tables, etc, and generate the necessary SQL. Oh, and I can also include chunks for POD if desired. Highly Recommended! Lee Wittenberg : noweb, nuweb, Funnelweb, or any of the language independents should do the job. 14-Mar-1998 23:45:51-GMT,1274;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 QAA01824 for ; Sat, 14 Mar 1998 16:45: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, 14 Mar 1998 14:11:15 EST From: Darran Edmundson Reply-To: LitProg@SHSU.edu, dEdmundson@Bigfoot.com Subject: [Q] F development with FWEB ... Date: 14 Mar 1998 19:41:01 GMT Message-ID: <6eemgd$hs2$1@murdoch.acc.Virginia.EDU> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit To: LitProg@SHSU.edu After migrating from F77 to F90 several months ago, I am now going one step further and, for many numeric tasks, moving to the F90 subset language F (http://kumo.swcp.com/imagine1/). Unfortunately, F doesn't handle the fixed source of old Fortran, which is what FWEB generates even in F90 mode. Is it possible for FWEB to output free-form code? -- Darran Edmundson (dEdmundson@Bigfoot.com) Visiting Canadian NSERC Fellow Optical Sciences Centre, Australian National University 18-Mar-1998 15:36:11-GMT,2706;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 IAA22264 for ; Wed, 18 Mar 1998 08:36:10 -0700 (MST) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from robert-morris.edu (rmcnet.robert-morris.edu) by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Wed, 18 Mar 1998 09:23:33 EST Date: Wed, 18 Mar 1998 10:23:45 -0500 From: "Bennett, David" Reply-To: LitProg@SHSU.edu, bennett@rmcnet.robert-morris.edu To: LITPROG@SHSU.edu Subject: Position Announcement Message-ID: Assistant/Associate Professors COMMUNICATIONS AND INFORMATION SYSTEMS Robert Morris College Pittsburgh, PA The School of Communications and Information Systems (SCIS) seeks candidates to help implement its innovative undergraduate Communications Skills Program and new interdisciplinary Master's program in communications and information science/systems. REQUIREMENTS Ph.D. degree in relevant field and will be competitive for a joint appointment in Communications and in Computer and Information Systems. Evidence of experience in bridging the disciplines of rhetoric/communication theory and information theory; record of excellent teaching, service, and scholarship; business and/or corporate experience. Interdisciplinary background and supporting credentials in more than one of the following fields: information management, systems theory, systems analysis, software applications, multimedia, computer assisted instruction and presentations, distance learning, applied linguistics, and/or communication law and ethics. Assist in implementing its innovative undergraduate Communications Skills Program and new interdisciplinary master's program in communications and information science/systems. Teaching assignments may include evening and Saturday schedules. Robert Morris College is consistently named among the top ten specialty schools in the USA. RMC offers undergraduate and graduate degree programs to about 5,000 students at two locations in Pittsburgh, PA. Submit a letter of interest, resume, three references, and statement delineating interdisciplinary experience in appropriate fields to: DIRECTOR OF HUMAN RESOURCES ROBERT MORRIS COLLEGE 881 NARROWS RUN ROAD MOON TOWNSHIP, PA 15108 Robert Morris College is an equal opportunity employer. For more information, contact Dr. John O'Banion Head, Department of Communications Robert Morris College obanion@robert-morris.edu 18-Mar-1998 18:31:50-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 LAA27343 for ; Wed, 18 Mar 1998 11:31:48 -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, 18 Mar 1998 12:03:36 EST From: thompson@sun1.coe.ttu.edu Subject: comp.programming.literate FAQ Date: 18 Mar 1998 12:50:13 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. 19-Mar-1998 18:12:17-GMT,1174;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 LAA02420 for ; Thu, 19 Mar 1998 11:12: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, 19 Mar 1998 11:56:19 EST Message-ID: <35113310.E3FD5854@objectint.com> Date: Thu, 19 Mar 1998 10:00:32 -0500 From: "Eric S. Paro" Reply-To: LitProg@SHSU.edu, ericp@objectint.com MIME-Version: 1.0 Subject: Smalltalk Pros Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit To: LitProg@SHSU.edu Please pardon the intrusion to the group, but we need to hire additional Smalltalk programmers/developers. Please see our post in misc.jobs.contract, misc.jobs.offered or triangle.jobs. If you don't have access to those groups, please contact: ObjectIntelligence Corporation 900 Ridgefield Drive, Suite 240 Raleigh,NC 27609 800-789-6595 voice (alternate 919.878.6690) 800-789-0712 fax dianal@objectint.com 20-Mar-1998 13:37:06-GMT,1473;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 GAA29748 for ; Fri, 20 Mar 1998 06:37:05 -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, 20 Mar 1998 07:21:50 EST Message-ID: <35126DA5.467@BodSch.BenP.WAU.NL> Date: Fri, 20 Mar 1998 14:22:45 +0100 From: Chris van Uffelen Reply-To: LitProg@SHSU.edu, Chris.vanUffelen@BodSch.BenP.WAU.NL MIME-Version: 1.0 Subject: multi-file sources in NOWEB Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit To: LitProg@SHSU.edu Hi there, I remember there have been some discussions on multi-file sources lately. I think in noweb it's as easy as this (no perl, awk etc needed) Prepare a master TeX file like: <>= \documentclass{article} \usepackage{noweb} \begin{document} <> \end{document} @ Including noweaved files is simple. <>= \input{source.1} % source.1.tex is included \input{source.2} % source.2.tex is included @ The sources are noweaved .nw files. With x = 1,2: <>= Here is your code. <<*>>= blah blah @ \endinput probably everybody programs like this for a long time already, cheers Chris 23-Mar-1998 11:26:29-GMT,1257;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 EAA21728 for ; Mon, 23 Mar 1998 04:26: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; Mon, 23 Mar 1998 05:05:44 EST From: "Markus.Oellinger" Reply-To: LitProg@SHSU.edu, ollinger@xenon.pseg.siemens.at Subject: Re: Book-style CWEB output? Date: 23 Mar 1998 10:51:25 GMT Message-ID: <6f5erd$hdh$1@elna.ethz.ch> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit To: LitProg@SHSU.edu Jason Alexander wrote: > > Does anyone know if it is possible to easily get book-style output > (i.e., with chapters, table of contents, and the index at the end) from > Cweave? > > If so, does this require rewriting parts of the TeX input file used by > the generated TeX file, or does it require a different version of the > Cweave executable? You might consider mCWEB as an alternative. To be found at ftp.ist.tu-graz.ac.at/pub/software/packages/CWeb Mark. 23-Mar-1998 11:33:04-GMT,1776;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 EAA21849 for ; Mon, 23 Mar 1998 04:33: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; Mon, 23 Mar 1998 05:05:40 EST From: "Markus.Oellinger" Reply-To: LitProg@SHSU.edu, ollinger@xenon.pseg.siemens.at Subject: Re: modular literate programming Date: 23 Mar 1998 10:50:39 GMT Message-ID: <6f5epv$hde$1@elna.ethz.ch> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit To: LitProg@SHSU.edu Daniel Heck wrote: > > David Martin wrote: > > > I am trying to find a way to do literate programming in a modular > > manner, and have not found a satisfactory way to do so with noweb. The > > noweb model seems to be that there is _one_ noweb file. This is clearly > > not satisfactory. Putting multiple noweb files on the tangle > > command-line is not general, and also not satisfacory. > > > > Am I missing an elegant solution for noweb? Or should I use nuweb, > > which has an include directive? > > LaTeX and C++ is my modus operandi, if that makes a difference... > > Did you ever take a look at CWEB? As far as I know, CWEB supports modular > programming -- at least to some extend. Not true. Although I think that noweb should be able to handle multiple input files, you should check out mCWEB at ftp://ftp.ist.tu-graz.ac.at/pub/software/packages/CWeb, a CWEB version that can indeed handle multiple input files (Unix only). > > > David Martin > > Daniel Heck 24-Mar-1998 1:02:47-GMT,1204;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 SAA10804 for ; Mon, 23 Mar 1998 18:02:45 -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; Mon, 23 Mar 1998 14:09:59 EST Message-ID: <3516B769.14FDE355@objectint.com> From: "Eric S. Paro" Reply-To: LitProg@SHSU.edu, ericp@objectint.com MIME-Version: 1.0 Subject: Smalltalk Opportunities Open in the USA!!!!!!! Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit Date: Mon, 23 Mar 1998 19:23:54 GMT To: LitProg@SHSU.edu Please pardon the intrusion to the group, but we need to hire additional Smalltalk programmers/developers. Please see our post in misc.jobs.contract, misc.jobs.offered or triangle.jobs. If you don't have access to those groups, please contact: ObjectIntelligence Corporation 900 Ridgefield Drive, Suite 240 Raleigh,NC 27609 800-789-6595 voice (alternate 919.878.6690) 800-789-0712 fax dianal@objectint.com 24-Mar-1998 6:47:16-GMT,2303;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 XAA21492 for ; Mon, 23 Mar 1998 23:47:14 -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; Mon, 23 Mar 1998 11:16:44 EST From: "Edward K. Ream" Subject: LEO 1.0 Alpha for Macintosh Date: 21 Mar 1998 21:36:40 GMT Message-ID: <6f1bt8$sjc$1@murdoch.acc.Virginia.EDU> Reply-To: LitProg@SHSU.edu, edream@mailbag.com MIME-Version: 1.0 Content-Type: text/plain; charset=iso-8859-1 Content-Transfer-Encoding: 8bit To: LitProg@SHSU.edu Announcing LEO version 1.0 for Macintosh MacOS. (Future versions of LEO will run on Windows 95/NT) This alpha version of LEO is free, and a reward for bugs is offered. LEO can be used by C, C++ and Objective-C programmers. LEO is a "literate outliner", that is, a text editor supporting outlining and a simplified literate programming language called SWEB. The combination of outlines and SWEB creates a new and highly enjoyable literate programming environment. ----- Features • Linked outline and text panes. The text pane shows the text associated with the currently selected headline in the outline pane. • Superb outlining features. Headlines are true objects, not markers into flat text. Headlines can be expanded, contracted, moved, reorganized or cloned easily. Clones provide a powerful way of creating multiple, linked views of a single program. • Multiple outline windows can be open simultaneously. • Fast search/change commands take advantage of outline organization. • Automatic syntax coloring of text. • Several fast Tangle commands translate SWEB into C source files. • Fast incremental file writes, even for huge outlines. • A Print command that typesets an outline without using TeX. • Full documentation, including an outline containing parts of LEO's source code. ----- Availability For a free copy of LEO for MacOS contact me at: edream@mailbag.com LEO's documentation is available online at http://www.mailbag.com/users/edream/front.html Edward K. Ream edream@mailbag.com (608) 231-0766 24-Mar-1998 11:16:26-GMT,2984;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 EAA14584 for ; Tue, 24 Mar 1998 04:16: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; Tue, 24 Mar 1998 04:56:23 EST From: Sven Utcke Reply-To: LitProg@SHSU.edu, utcke@tu-harburg.de Subject: Re: modular literate programming Date: 24 Mar 1998 10:13:29 GMT Message-ID: <6f8109$n1r$1@elna.ethz.ch> To: LitProg@SHSU.edu "Markus.Oellinger" writes: > Daniel Heck wrote: > > > > David Martin wrote: > > > > > I am trying to find a way to do literate programming in a modular > > > manner, and have not found a satisfactory way to do so with noweb. The > > > noweb model seems to be that there is _one_ noweb file. This is clearly > > > not satisfactory. Putting multiple noweb files on the tangle > > > command-line is not general, and also not satisfacory. > > > > > > Am I missing an elegant solution for noweb? Or should I use nuweb, > > > which has an include directive? > > > LaTeX and C++ is my modus operandi, if that makes a difference... > > > > Did you ever take a look at CWEB? As far as I know, CWEB supports modular > > programming -- at least to some extend. > Not true. Although I think that noweb should be able to handle multiple > input files, you should check out mCWEB at > ftp://ftp.ist.tu-graz.ac.at/pub/software/packages/CWeb, a CWEB version > that can indeed handle multiple input files (Unix only). Well, now that we're all touting our favourite web-dialect, let me just add that FWEB supports multiple input-files (includes and all that). However, truth be told, while I did use this feature in the beginning I didn't really found it worthwhile. Except maybe for a huge (book-like) projekt, I can't see why you would want it. And there IS the namespace-problem, of course. However, having said that, there is a mode in FWEB that will parse another FWEB-file for definitions and such without actually including the web. This way the pretty-printer isn't confused so easily when stumbling about variables/functions/definitions defined in a different file. I found that one quite handy. Sven PS: Version 1.53 can be found on ftp://ftp.pppl.gov/pub/fweb/ Version 1.6 is due anytime now (i.e. May), but 1.53 works quite well, except for the language-independent mode. -- Lehrstuhl fuer Mustererkennung und Bildverarbeitung | | Sven Utcke | ` \ _ \ phone: +49 761 203 8267 Am Fluhafen 17 _|_|_|_|_.__/ fax : +49 761 203 8262 79085 Freiburg i. Brsg. mailto:utcke@informatik.uni-freiburg.de www.informatik.uni-freiburg.de/~lmb 25-Mar-1998 0:28:52-GMT,1831;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 RAA18379 for ; Tue, 24 Mar 1998 17:28: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; Tue, 24 Mar 1998 18:15:10 EST From: ioffrigga@aol.com (Iof frigga) Reply-To: LitProg@SHSU.edu, ioffrigga@aol.com Subject: My programs, at my website....i need feedback Date: 25 Mar 1998 00:11:20 GMT Message-ID: <1998032500112000.TAA14721@ladder03.news.aol.com> To: LitProg@SHSU.edu i would apriciate it if someone would check out my page, it is for my software company -frigg software, inc. http://members.tripod.com/~friggcorp/index.htm please emai me telling me what you think at: iof frigga@aol.com -------------------------- while you are there please feel free to sign up for my mailing list, and check out our sponsers. -----sponsers--------- WebPromote: http://ad1.webpromote.com/wplink?AP13388 submit your site to many search engines and get it know while you are there please check out their free mailing list. - Register-It! http://www.register-it.com/start.cgi?banner=ref255c5ccb also a great place to submit your site, plesae check it out. - WebSiteGarage http://www.websitegarage.com/ref.cgi?banner=refee51c9a4 The Best plase to tune up your site, they will atomatically show you how to update your page, and make it more atractive. (they also have free features!) -------------------------------- thanks, frigg inc. frigg_inc@juno.com http://members.tripod.com/~friggcorp/index.htm http://ad1.webpromote.com/wplink?AP13388 http://www.websitegarage.com/ref.cgi?banner=refee51c9a4 25-Mar-1998 3:32:41-GMT,3011;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 UAA24693 for ; Tue, 24 Mar 1998 20:32:40 -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; Tue, 24 Mar 1998 21:28:29 EST From: Yann Kieffer Reply-To: LitProg@SHSU.edu, Yann.Kieffer@imag.fr Subject: Literate Programming systems diversity Date: 25 Mar 1998 03:15:40 GMT Message-ID: <6f9sst$bph$1@news.interlog.com> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit To: LitProg@SHSU.edu Markus.Oellinger wrote: > > Daniel Heck wrote: > > Did you ever take a look at CWEB? As far as I know, CWEB supports modular > > programming -- at least to some extend. > > Not true. Although I think that noweb should be able to handle multiple > input files, you should check out mCWEB at > ftp://ftp.ist.tu-graz.ac.at/pub/software/packages/CWeb, a CWEB version > that can indeed handle multiple input files (Unix only). and in another message: Markus.Oellinger wrote: > > Jason Alexander wrote: > > Does anyone know if it is possible to easily get book-style output > > (i.e., with chapters, table of contents, and the index at the end) from > > Cweave? > > > > If so, does this require rewriting parts of the TeX input file used by > > the generated TeX file, or does it require a different version of the > > Cweave executable? > > You might consider mCWEB as an alternative. To be found at > ftp.ist.tu-graz.ac.at/pub/software/packages/CWeb Are you advertising something? :-) There's something I hate out there, it's the fact that there's nearly as much literate programming software as programmers. Why not all stick to some standard? I like the Knuth way very much - and it sort of proved to be effective: TeX: The Program, Metafont: The Program, The CWEB System of Structured Documentation and The Stanford Graphbase are four books (by Knuth!) that are programs. And the two last (written in CWEB) definitely have multiple input files. They do have cross-references and a general index; I think Knuth explained how he achieved that somwhere in "CWEB..." or in the doc of the CWEB package (probably both). I don't say this is the only way to go - but if someone designs something else, there should at least be some joint interest in this other way. Sort of what happened with LaTeX (which seems to be partly responsible for this variety of systems: LaTeX really doesn't help much with that sort of writing). Even the FAQ doesn't say much about CWEB; Knuth is not going to advertise it any harder than through the two last books I've quoted (unless he writes some other :) ). Yann PS: of course, each time I'm talking about Knuth, I'm forgetting Sylvio Levy; so please read "Knuth and Levy" instead... 25-Mar-1998 22:57:52-GMT,1611;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 PAA20036 for ; Wed, 25 Mar 1998 15:57: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; Wed, 25 Mar 1998 16:39:36 EST From: Chadhas Reply-To: LitProg@SHSU.edu, chadhas@poboxes.com Subject: global char variables help Date: Thu, 26 Mar 1998 01:59:30 +0000 Message-ID: <3519B682.B2F22655@poboxes.com> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit To: LitProg@SHSU.edu Hi, I need some help. I need to use some global variables which are of the char type. Well these variables are atleast 20 chars long for example a[20]. Well I decalre them outside even outside main in the following way. char a[20]; well anway now in main i try to assign a value to them for example the word door. so i use the syntax a="door"; well it gives and error, lvalue required. Anwaay I can get around this problem by not declaring it as a global variable and declaring it when I use it witht the following syntax char a[20]="door"; it works but then I can't use it in any other function. Are there any solutions. I need this help urgently as part of a project I'm working on. Any suggestions or ideas on how to fix this problem would be really appreciated. Reply to chadhas@poboxes.com or otherwise in the newsgroup Shiv Chadha 26-Mar-1998 11:18:20-GMT,3016;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 EAA12875 for ; Thu, 26 Mar 1998 04:18:18 -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, 26 Mar 1998 05:11:15 EST From: Yann Kieffer Reply-To: LitProg@SHSU.edu, Yann.Kieffer@imag.fr Subject: Literate Programming systems diversity Date: 24 Mar 1998 16:00:44 GMT Message-ID: <6f8lbc$k66$1@murdoch.acc.Virginia.EDU> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit To: LitProg@SHSU.edu Markus.Oellinger wrote: > > Daniel Heck wrote: > > Did you ever take a look at CWEB? As far as I know, CWEB supports modular > > programming -- at least to some extend. > > Not true. Although I think that noweb should be able to handle multiple > input files, you should check out mCWEB at > ftp://ftp.ist.tu-graz.ac.at/pub/software/packages/CWeb, a CWEB version > that can indeed handle multiple input files (Unix only). and in another message: Markus.Oellinger wrote: > > Jason Alexander wrote: > > Does anyone know if it is possible to easily get book-style output > > (i.e., with chapters, table of contents, and the index at the end) from > > Cweave? > > > > If so, does this require rewriting parts of the TeX input file used by > > the generated TeX file, or does it require a different version of the > > Cweave executable? > > You might consider mCWEB as an alternative. To be found at > ftp.ist.tu-graz.ac.at/pub/software/packages/CWeb Are you advertising something? :-) There's something I hate out there, it's the fact that there's nearly as much literate programming software as programmers. Why not all stick to some standard? I like the Knuth way very much - and it sort of proved to be effective: TeX: The Program, Metafont: The Program, The CWEB System of Structured Documentation and The Stanford Graphbase are four books (by Knuth!) that are programs. And the two last (written in CWEB) definitely have multiple input files. They do have cross-references and a general index; I think Knuth explained how he achieved that somwhere in "CWEB..." or in the doc of the CWEB package (probably both). I don't say this is the only way to go - but if someone designs something else, there should at least be some joint interest in this other way. Sort of what happened with LaTeX (which seems to be partly responsible for this variety of systems: LaTeX really doesn't help much with that sort of writing). Even the FAQ doesn't say much about CWEB; Knuth is not going to advertise it any harder than through the two last books I've quoted (unless he writes some other :) ). Yann PS: of course, each time I'm talking about Knuth, I'm forgetting Sylvio Levy; so please read "Knuth and Levy" instead... 26-Mar-1998 11:19:56-GMT,3500;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 EAA12903 for ; Thu, 26 Mar 1998 04:19:54 -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, 26 Mar 1998 05:11:30 EST From: Yann Kieffer Reply-To: LitProg@SHSU.edu, Yann.Kieffer@imag.fr Subject: Re: Literate Programming systems diversity Date: 26 Mar 1998 10:09:56 GMT Message-ID: <6fd9hk$etp$1@murdoch.acc.Virginia.EDU> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit To: LitProg@SHSU.edu > Marc van Leeuwen wrote: > >> - I think Don is the greatest when it comes to algorithms, writing, > >> and ideas, but his instincts as a tool builder are not good: tons > >> of complexity in order to get the last drop of ink in exactly the > >> right place on the page. The ``worse is better'' approach really > >> is better. Well, Word is really `worse', and I really hate it. > >I think this is not really fair to Don, especially if you apply it to > >TeX, which obviously satisfies lots of people better than other > >available alternatives; I think this is at least partly due to the fact > >that it allows you to get the last drop of ink in exactly the right > >place on the page (and in most cases it gets there automatically). Which is supposedly the same place whatever computer you're using... > I think TeX is a brilliant illustration of everything that is right > and wrong about Don's work. The algorithms and underlying model are > wonderful, simple, and absolute category killers. The documentation > (TeXbook) is peerless. And some of the real complexity (parshapes, > looseness, hyphenation) is totally justified in terms of the goals. > Some of the complexity (e.g., portability support) is Knuthian tour > de force. Would you expect it to work the MicroSoft way? Works here, hangs there... uh oh, my margins changed when I changed my printer... > On the other hand, to quote Michael Plass, "Don tried very hard not to > make TeX a programming language, and he almost succeeded." I don't > know many people who fully understand its `digestive' model of > execution. And...? Do you understand how Word is working inside? You don't need that kind of knowledge if you're not designing big macro packages. And if you need this knowledge, it's worthing giving it a second try: the TeXBook is pretty dense, but sometime, it's so smoothly written that you just don't expect that much complexity. And don't skim the exercises! > I think the real complexity of CWEB comes from mixing functions that > should be kept separate. In particular, from putting typesetting > commands in the code, and from trying to control the prettyprinter. It sounds to me that you can't do much pretty-printing in a straighforward way. So the first choice would be, to pretty-print or not to pretty-print... As a reader of The Stanford Graphbase (which I have in paper form), I have to say that the more I read it, the more I love it. Now it's my first experience with lp (I haven't coded a single line yet, I'm mainly trying to make up my mind... but I won't try dozens of them just for the sake of trying), so perhaps it just means I love lp. Yann 26-Mar-1998 15:15:08-GMT,1800;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 IAA17383 for ; Thu, 26 Mar 1998 08:15:07 -0700 (MST) X-ListName: Literate Programming Discussion List Warnings-To: <> Errors-To: owner-litprog@SHSU.edu Sender: owner-litprog@SHSU.edu Received: from acquire.stern.nyu.edu by Niord.shsu.edu (MX V4.1 AXP) with SMTP; Thu, 26 Mar 1998 09:01:22 EST Received: from db.stern.nyu.edu (db.stern.nyu.edu [128.122.185.52]) by acquire.stern.nyu.edu (8.8.8/8.8.8) with ESMTP id KAA06058 for ; Thu, 26 Mar 1998 10:01:20 -0500 (EST) Received: from localhost (fchen@localhost) by db.stern.nyu.edu (8.8.5/8.8.5) with SMTP id KAA01905 for ; Thu, 26 Mar 1998 10:01:20 -0500 (EST) Date: Thu, 26 Mar 1998 10:01:20 -0500 (EST) From: Fei Chen Reply-To: LitProg@SHSU.edu, fchen@stern.nyu.edu To: literate programming Subject: strange CWEB behavior Message-ID: MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII hi all, i encounter the following error with LaTeX (1996/12/01) --- [34] [35] [36] [37] [38] [39] *28 [40] [41] [42] [43] (nn1.bbl [44]) Runaway argument? ! Paragraph ended before \cweb@skip_end was complete. \par l.2392 ? ! Undefined control sequence. l.2397 \inx ? ! Undefined control sequence. l.2398 \fin ? ! Undefined control sequence. l.2399 \con ? ) * ! Emergency stop. ------ but the strange thing is that it compiles without error with LaTeX (1996/6/01). i don't understand why. can anyone help? (i'm using the cweb documentclass) thanks very much, fei 27-Mar-1998 2:09:02-GMT,1068;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 TAA02950 for ; Thu, 26 Mar 1998 19:09:01 -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; Thu, 26 Mar 1998 19:56:45 EST Received: (from mcclaine@juno.com) by x3.boston.juno.com (queuemail) id UaH15807; Thu, 26 Mar 1998 20:55:55 EST To: LISTSERV@SHSU.edu CC: LitProg@SHSU.edu Date: Thu, 26 Mar 1998 20:01:43 -0500 Message-ID: <19980326.205433.3270.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] 27-Mar-1998 2:09:43-GMT,8342;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 TAA02966 for ; Thu, 26 Mar 1998 19:09: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, 26 Mar 1998 19:22:34 EST From: Marc van Leeuwen Reply-To: LitProg@SHSU.edu, maavl@zenon.univ-poitiers.fr Subject: Re: Literate Programming systems diversity Date: 25 Mar 1998 10:17:01 GMT Message-ID: <6falit$oaj$1@murdoch.acc.Virginia.EDU> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit To: LitProg@SHSU.edu Norman Ramsey wrote: > > In article <6f8lbc$k66$1@murdoch.acc.Virginia.EDU>, > Yann Kieffer wrote: > >I like the Knuth way very much - and it sort of proved to be effective: > >TeX: The Program, Metafont: The Program, The CWEB System of Structured > >Documentation and The Stanford Graphbase are four books (by Knuth!) > >that are programs. And the two last (written in CWEB) definitely > >have multiple input files. They do have cross-references and a > >general index; I think Knuth explained how he achieved that somwhere > >in "CWEB..." or in the doc of the CWEB package (probably both). > > Yes, and those four books required two different literate-programming > tools (Original WEB and Levy CWEB) plus the CTWILL tool for generating > the indices. > > >Why not all stick to some standard? > > There's more to life than C programming > [...] > This argument doesn't explain why there are so many variations on > CWEB. My theory, unsubstantiated by evidence, is that CWEB is too > closely based on Don Knuth's original WEB. This has two problems: > > - Support for LaTeX is either unavailable or not obvious (Joachim > Schrod's macros). > > - I think Don is the greatest when it comes to algorithms, writing, > and ideas, but his instincts as a tool builder are not good: tons > of complexity in order to get the last drop of ink in exactly the > right place on the page. The ``worse is better'' approach really > is better. I think this is not really fair to Don, especially if you apply it to TeX, which obviously satisfies lots of people better than other available alternatives; I think this is at least partly due to the fact that it allows you to get the last drop of ink in exactly the right place on the page (and in most cases it gets there automatically). Which is not to say I think TeX could not be improved, but I would have different reasons for that. Also I think attributing tons of complexity to CWEB is a great exaggeration; according to your own count it has 27 commands (probably a few more now) which I guess is less even than the amount of possible options you can give to noweb (I haven't counted). All told, CWEB is an extremely simple system in terms of the amount of facilities it provides, certainly when compared to TeX (probably also compared to noweb, when you count all the extensions). There is a different problem with CWEB, in my opinion: while its external interface is not complicated (and the documentation correspondingly limited), there are some complicated aspects of its internal workings that most users are not aware of, and that are prone to lead to surprise and bewilderment. In particular this applies to CWEAVE's prettyprinter, which is based on an incomprehensible grammar that is supposed to always automatically produce beautiful results, but in many cases fails miserably. It is my guess that the resulting frustration has led many literate programmers to eschew prettyprinting altogether. As far as the adequacy of CWEB (or indeed other current LP systems) as a universal tool for literate programming is concerned, I had a discussion with Don about this in 1996 during a visit he made to Amsterdam, which has been recorded in TUGboat (Vol 17 (1996), No 4, pp 353-355). It is to long to quote here, so I have to limit myself to some quotes (out of context, unfortunately) of Don's replies "It is a hypertext way of programming and I imagine that with better hypertext systems [...] we're going to get a variety of new incompatible systems that will support literate programming. Hopefully somebody with time and talent, and taste, will put together a system of literate programming that is so charming it will captivate a lot of people. "One programming language is good enough for me [...] For "The art of Computer Programming", for the next twenty years, I'm pretty sure that CWEB is going to be as good as anything I need. I'll write programs for Mathematica and I'll write some programs for MetaPost; I could develop or use LP for those programs, but I don't think I will. [...] But with CWEB I'm going to write an average of five programs a week for a forseeable future [...] [w.r.t. mini-indexes:] These minimalistic systems are attractive primarily because a good programmer can write them in a couple of days, understand them and use them, and get a lot of mileage out of them. Once somebody writes a good hypertext system for literate programming, I think that'll attract a lot of people [...] The time for that will be ripe in about two years." That's now! While I don't necessarily agree with everything Knuth says, it is clear that he far from considers CWEB a definite solution for literate programming, even with respect to the language C. As a creator of a variant of CWEB (namely CWEBx) I am responsible for part of the diversity that Yann detests. I had good reasons to do so (and maybe some bad ones as well) and I can do things with the resulting program that cannot possibly be done with CWEB (nor incidentally with noweb). I hope the improvement will be useful to other people as well, and I have done considerable effort to provide proper documentation, publicity, and compatibility with CWEB, but this is all I can do. Markus Oellinger has apparently done something similar for slightly different reasons (although mCWEB shares at least one new feature---parsing header files---with CWEBx) and from the look of it, his reasons were excellent and he has done a good job. Of course I would have been happier had he based his version on CWEBx rather than CWEB (I am vain enough to believe it would have made his task easier), but he is completely justified in doing what he deems best. The toolbox enthousiasts, like Norman, can of course see this as evidence that their approach is superior to that of a single, non-extensible tool like CWEB. To those who, like myself, believe that certain behaviour simply cannot be achieved by a generic system, and require a specialised tool that tackles the problem directly, the diversity in CWEB-like systems poses a challenge: to isolate those aspects of extensions that have been made that represent essential functionality, and are not too closely linked with a particular style of programming (I would like to evaluate this for Markus' additions), and to design a system that incorporates that functionality, while if possible providing a mechanism for tuning the behaviour in less fundamental aspects. Another important point (as stressed by Knuth) would be to provide a sufficiently clear user interface to such a system that learning would be natural and all routine tasks automated and easy; this is one area where a fixed tool has more promise than a toolbox, in my opinion. In summary, unity in the world of CWEB-like systems should come from the design of a more powerful and flexible system (but it might still be to early for that), not from everybody clinging to Levy/Knuth's private version. Marc van Leeuwen Universite de Poitiers http://wallis.univ-poitiers.fr/~maavl/ Actually I'm extremely glad to see the continuing development of languages, not only because programming languages are getting better and better in important ways, but also because such work soaks up a lot of people's energy---therefore computer scientists don't write papers that I would otherwise have to read, and I can get my books finished a lot sooner. -- Donald E. Knuth 27-Mar-1998 3:36:14-GMT,2494;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 UAA04718 for ; Thu, 26 Mar 1998 20:36:08 -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, 26 Mar 1998 21:31:48 EST From: Norman Ramsey Reply-To: LitProg@SHSU.edu, nr@cs.virginia.edu Subject: Re: Literate Programming systems diversity Date: 24 Mar 1998 16:14:31 GMT Message-ID: <6f8m57$kmk$1@murdoch.acc.Virginia.EDU> To: LitProg@SHSU.edu In article <6f8lbc$k66$1@murdoch.acc.Virginia.EDU>, Yann Kieffer wrote: >I like the Knuth way very much - and it sort of proved to be effective: >TeX: The Program, Metafont: The Program, The CWEB System of Structured >Documentation and The Stanford Graphbase are four books (by Knuth!) >that are programs. And the two last (written in CWEB) definitely >have multiple input files. They do have cross-references and a >general index; I think Knuth explained how he achieved that somwhere >in "CWEB..." or in the doc of the CWEB package (probably both). Yes, and those four books required two different literate-programming tools (Original WEB and Levy CWEB) plus the CTWILL tool for generating the indices. >Why not all stick to some standard? There's more to life than C programming, and generally people are willing to pick a different tool if it has better support for the programming language of the week. The language-independent literate-programming tools are successful because some people use more than one programming language. This argument doesn't explain why there are so many variations on CWEB. My theory, unsubstantiated by evidence, is that CWEB is too closely based on Don Knuth's original WEB. This has two problems: - Support for LaTeX is either unavailable or not obvious (Joachim Schrod's macros). - I think Don is the greatest when it comes to algorithms, writing, and ideas, but his instincts as a tool builder are not good: tons of complexity in order to get the last drop of ink in exactly the right place on the page. The ``worse is better'' approach really is better. Norman P.S. For worse is better, see Gabriel, Richard P. 1991 (June). Lisp: Good news, bad news, how to win big. _AI Expert_, 6(6):30--39. 27-Mar-1998 21:54:37-GMT,2092;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 OAA27577 for ; Fri, 27 Mar 1998 14:54:36 -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, 27 Mar 1998 14:47:52 EST From: Norman Ramsey Reply-To: LitProg@SHSU.edu, nr@cs.virginia.edu Subject: Re: Literate Programming systems diversity Date: 26 Mar 1998 15:27:24 GMT Message-ID: <6fds4s$o6j$1@murdoch.acc.Virginia.EDU> To: LitProg@SHSU.edu In article <6fd9hk$etp$1@murdoch.acc.Virginia.EDU>, Yann Kieffer wrote: >> >> right place on the page. The ``worse is better'' approach really >> >> is better. > >Well, Word is really `worse', and I really hate it. I don't think it's fair to characterize Word as either ``worse is better'' or ``do the right thing.'' Dick Gabriel was talking about strategies used by people whose goal is to produce good software. The people who gave us Word are different: their goal is to capture a marketplace and make money. The strategy that seems to work is to get out a product that has a lot of alleged features, and to do so quickly. It doesn't matter if the product actually works. >> On the other hand, to quote Michael Plass, "Don tried very hard not to >> make TeX a programming language, and he almost succeeded." I don't >> know many people who fully understand its `digestive' model of >> execution. > >You don't need that kind of knowledge if you're not designing >big macro packages. You need that kind of knowledge if you care about where the ink lands on the page. And if you don't care, why use TeX? (Half-facetious; there are other reasons to use TeX.) >It sounds to me that you can't do much pretty-printing in >a straighforward way. So the first choice would be, to >pretty-print or not to pretty-print... Truer words were never spoke... N 27-Mar-1998 23:04:35-GMT,3912;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 QAA29284 for ; Fri, 27 Mar 1998 16:04:33 -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, 27 Mar 1998 16:59:17 EST From: Norman Ramsey Reply-To: LitProg@SHSU.edu, nr@cs.virginia.edu Subject: Re: Literate Programming systems diversity Date: 25 Mar 1998 16:33:26 GMT Message-ID: <6fbbkm$7vr$1@murdoch.acc.Virginia.EDU> To: LitProg@SHSU.edu In article <6falit$oaj$1@murdoch.acc.Virginia.EDU>, Marc van Leeuwen wrote: >> - I think Don is the greatest when it comes to algorithms, writing, >> and ideas, but his instincts as a tool builder are not good: tons >> of complexity in order to get the last drop of ink in exactly the >> right place on the page. The ``worse is better'' approach really >> is better. > >I think this is not really fair to Don, especially if you apply it to >TeX, which obviously satisfies lots of people better than other >available alternatives; I think this is at least partly due to the fact >that it allows you to get the last drop of ink in exactly the right >place on the page (and in most cases it gets there automatically). I think TeX is a brilliant illustration of everything that is right and wrong about Don's work. The algorithms and underlying model are wonderful, simple, and absolute category killers. The documentation (TeXbook) is peerless. And some of the real complexity (parshapes, looseness, hyphenation) is totally justified in terms of the goals. Some of the complexity (e.g., portability support) is Knuthian tour de force. On the other hand, to quote Michael Plass, "Don tried very hard not to make TeX a programming language, and he almost succeeded." I don't know many people who fully understand its `digestive' model of execution. >Also I think attributing tons of complexity to CWEB is a great >exaggeration; according to your own count it has 27 commands (probably a I think the real complexity of CWEB comes from mixing functions that should be kept separate. In particular, from putting typesetting commands in the code, and from trying to control the prettyprinter. Our experience with using CWEB and similar tools for serious projects was that people burned enormous amounts of time typesetting. Some programmers also suffered tremendously from having the source code they edited be so different from the output they saw (others didn't). 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. >few more now) which I guess is less even than the amount of possible >options you can give to noweb (I haven't counted). The proliferation of command-line options in noweb is my greatest embarrassment. I would be afraid to count :-) I would still argue, however, that if there must be complexity, the command line is the right place for it, not the source file. I welcome suggestions about eliminating some of those damn options. Noweb is going to undergo a major revision soon, perhaps this summer. >To those who, like myself, believe that >certain behaviour simply cannot be achieved by a generic system, and >require a specialised tool that tackles the problem directly Please tell us more about what sorts of things can be done in CWEB that can't be done in a generic system. One of the experiments in noweb was to see if specialized tools could be implemented as noweb filters, while keeping the basic machinery intact. I am always curious about the viability of this approach. Norman 28-Mar-1998 14:19:08-GMT,1062;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 HAA16499 for ; Sat, 28 Mar 1998 07:19:07 -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; Sat, 28 Mar 1998 08:15:04 EST Received: (from mcclaine@juno.com) by x3.boston.juno.com (queuemail) id J~G14786; Sat, 28 Mar 1998 09:14:30 EST To: LISTSERV@SHSU.edu CC: LitProg@SHSU.edu Date: Fri, 27 Mar 1998 21:47:33 -0500 Message-ID: <19980328.091240.10326.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] 29-Mar-1998 2:38:12-GMT,1361;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 TAA00583 for ; Sat, 28 Mar 1998 19:38:11 -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, 28 Mar 1998 20:35:02 EST From: Fei Chen Subject: strange CWEB behavior Date: 26 Mar 1998 16:33:43 GMT Message-ID: <6fe017$qsk$1@murdoch.acc.Virginia.EDU> Reply-To: LitProg@SHSU.edu, LitProg@SHSU.edu, fchen@stern.nyu.edu MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII To: LitProg@SHSU.edu hi all, i encounter the following error with LaTeX (1996/12/01) --- [34] [35] [36] [37] [38] [39] *28 [40] [41] [42] [43] (nn1.bbl [44]) Runaway argument? ! Paragraph ended before \cweb@skip_end was complete. \par l.2392 ? ! Undefined control sequence. l.2397 \inx ? ! Undefined control sequence. l.2398 \fin ? ! Undefined control sequence. l.2399 \con ? ) * ! Emergency stop. ------ but the strange thing is that it compiles without error with LaTeX (1996/6/01). i don't understand why. can anyone help? (i'm using the cweb documentclass) thanks very much, fei 29-Mar-1998 3:20:25-GMT,2894;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 UAA01375 for ; Sat, 28 Mar 1998 20:20: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; Sat, 28 Mar 1998 21:18:30 EST From: Balasubramanian Narasimhan Reply-To: LitProg@SHSU.edu, naras@stat.stanford.edu Subject: Re: Literate Programming systems diversity Date: 26 Mar 1998 17:56:33 GMT Message-ID: <6fe4sh$oq$1@murdoch.acc.Virginia.EDU> To: LitProg@SHSU.edu I view the diversity of lp systems as striking illustrations of the fecundity of Don's LP idea. I vaguely recall, perhaps in the same interview that Marc van Leeuwen mentions, how Don was disappointed that the original TeX macro language was not extended (used? I forget which) further. I have an inkling that he is not as disappointed with developments in LP, at least in the last few years. In fact, I once asked him directly what I should do about the fact that many of things I develop used several languages, not just one. And Don asked me to look into Noweb. Regarding the ``worse is better'' approach, I should also point to an article by Eric Raymond (The Cathedral and the Bazaar, http://sagan.earthspace.net/~esr/writings/cathedral-bazaar/). I think wouldn't be too far off the mark if I classify CWEB* as cathedrals, beautiful ones at that. Noweb, on the other hand, encourages the bazaar model better by allowing people to add their own filters quickly. I would be hard-pressed to hack cweb myself while Noweb wouldn't be that hard. Sure, a monolithic standard doesn't exist for lp systems. If we view LP systems as tools for *creating works of literature* (emphasis on Don's words) should there be one? I am reminded of a quote by George Marsaglia, in another context, regarding minimal-standard random number generators: But the idea of an industry standard smacks of stagnation and self-satisfaction. In using deterministic methods to simulate randomness we are all, as von Neumann said ``in a state of sin.'' Every deterministic scheme for producing randomness must have applications for which it gives bad results. Only the collective experience and imagination of developers and users of random number generators will lead to a better understanding of what those applications are. Only through encouraging--rather than stifling---experimentation can we, as Shakespeare urged, ``plate sin with gold.'' My $.02. ________________________________________________________________ B. Narasimhan naras@stat.stanford.edu http://www-stat.stanford.edu/~naras 29-Mar-1998 4:10:24-GMT,2676;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 VAA02253 for ; Sat, 28 Mar 1998 21:10: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; Sat, 28 Mar 1998 22:07:53 EST From: Lee Wittenberg Reply-To: LitProg@SHSU.edu, leew@samson.kean.edu Subject: Re: Literate Programming systems diversity Date: 29 Mar 1998 03:41:33 GMT Message-ID: <6fkftd$8kv$1@murdoch.acc.Virginia.EDU> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII To: LitProg@SHSU.edu On 25 Mar 1998, 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've played around a bit with noweb and Pretzel (although only in experimental code), and I prefer this to CWEB. As Norman knows, I happen to prefer prettyprinted code to typewriter font code. The Algol idea of separate publication and hardware languages (for human and machine consumption, respectively) is precisely analogous to LP's separation of weaving and tangling. Given that, why do I prefer noweb (with Pretzel filters)? Because I know that my preferences are personal -- that others prefer to see code monospaced. What noweb provides (with a little work) is a way for a single source file to be woven according to the reader's, rather than the author's, preferences. With noweb, I can prettprint my webs, but still share them with others, such as Norman, who do not want prettyprinting. I'm sure that when Norman weaves webs I send him, he doesn't run them through prettyprinting filters, but so what? The primary purpose of LP is to present programs in such a way that they are more accessible to human beings. Different people find different things easier (or harder) to read (which is why there are so many religious wars about syntax and so many different programming languages and LP tools). Why not let the reader choose for him or herself? -- 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 | ------------------------------------------------------------------------ 29-Mar-1998 5:41:50-GMT,10909;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 WAA03913 for ; Sat, 28 Mar 1998 22:41:48 -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, 28 Mar 1998 23:39:27 EST From: Marc van Leeuwen Reply-To: LitProg@SHSU.edu, maavl@zenon.univ-poitiers.fr Subject: Re: Literate Programming systems diversity Date: 27 Mar 1998 16:10:51 GMT Message-ID: <6fgj2b$bi0$1@murdoch.acc.Virginia.EDU> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit To: LitProg@SHSU.edu Norman Ramsey wrote: > > In article <6falit$oaj$1@murdoch.acc.Virginia.EDU>, > Marc van Leeuwen wrote: > >> - I think Don is the greatest when it comes to algorithms, writing, > >> and ideas, but his instincts as a tool builder are not good: tons > >> of complexity in order to get the last drop of ink in exactly the > >> right place on the page. > > >I think this is not really fair to Don, especially if you apply it to > >TeX, which obviously satisfies lots of people better than other > >available alternatives; I think this is at least partly due to the fact > >that it allows you to get the last drop of ink in exactly the right > >place on the page (and in most cases it gets there automatically). > > I think TeX is a brilliant illustration of everything that is right > and wrong about Don's work. The algorithms and underlying model are > wonderful, simple, and absolute category killers. The documentation > (TeXbook) is peerless. And some of the real complexity (parshapes, > looseness, hyphenation) is totally justified in terms of the goals. > Some of the complexity (e.g., portability support) is Knuthian tour > de force. > > On the other hand, to quote Michael Plass, "Don tried very hard not to > make TeX a programming language, and he almost succeeded." This is exactly what I believe is the greatest problem with TeX, and which I hinted at in my posting; note however that this has nothing to do with getting ink on the right place of the page. I think TeX should have allowed for a different mode of programming than macros. Macros are fine (and probably the best solution) when it comes to defining some routine but easy task; when it comes to writing a real algorithm, you are constantly dealing with their idiosyncracies rather than with the actual problem. > I don't know many people who fully understand its `digestive' model of > execution. In fact, it is not so much the difficulty of understanding it, as the difficulty of working with it. I think I understand the semantics of TeX's macros more fully than those of C's macros, but the difference is that in TeX I have to do everything with macros, while in C, I use them only for the most trivial tasks (for which I don't need to know the subtleties of the expansion rules). I must make one exception though, understanding the processing of alignments in TeX is in no way easy. Here is a challenge for people who think they understand: what happens in the following example? %\batchmode % set this to get a straight crash \halign{upart #\cr \global\let\endtemplate= \cr \endtemplate} \expandafter\let\expandafter\endv\endtemplate \def\!#1{\message{#1}} \def\trip{\endv} \halign{\!{a}A Ha\trip\egroup \def\bla{This is the $u$-part of the preamble............... }\bla\!\bla # \!{This is the v-part of the preamble} \cr Some text \!c & Some more text \par \end } (answer: it breaks TeX, but you'd have to very closely read TeX-The Program to understand why) > >Also I think attributing tons of complexity to CWEB is a great > >exaggeration; according to your own count it has 27 commands > > I think the real complexity of CWEB comes from mixing functions that > should be kept separate. In particular, from putting typesetting > commands in the code, and from trying to control the prettyprinter. I am not sure I understand what you mean by complexity. Sure, CWEB has a few codes that one may insert into C code, and which should be removed to get legal C, but since you'll have to tangle anyway, I don't see what is the problem with that. The codes themselves are extremely simple, things like inserting bits of space, or forced or optional line breaks; they do not interfere in any other way with the operation of CTANGLE or CWEAVE. The one exception is `@;', which is a bit subtle to learn to use properly, but this code does not make CWEB itself any more complex (it behaves exactly like a semicolon). > Our experience with using CWEB and similar tools for serious projects > was that people burned enormous amounts of time typesetting. Some > programmers also suffered tremendously from having the source code > they edited be so different from the output they saw (others didn't). It is ironic that a system that typesets code automatically would incite people to spend a lot of time on typesetting. One might expect that in a system without prettyprinting, where every space you type within the code immediately affects the "typeset" output, people would spend more time to get the layout just right. The explanation for this curious phenomenon is threefold, I think: (1) CWEB's formatting is seriously flawed; and it will fail to cope with many programs that the compiler accepts without problem; (2) users often lack the most fundamental knowledge about the way CWEAVE's parser sees the program, which would allow the majority of the problems to be fixed easily; (3) the little amount of control users get concerning the layout of programs is way too inflexible: if you are trying to change the automatically generated layout into a different style by inserting/killing line breaks and spacing, you are obviously not spending your time very wisely. I think that if automatic formatting would really be reliable, and allow some flexibilty in choosing the layout style (and indeed this should not happen inside the code, but globally, for instance on the command line), then you would in fact need to spend considerably less time on formatting. CWEBx goes some way in this direction, but it is certainly not perfect, and still probably somewhat biased towards my personal style preferences (this is not to say I force anybody to use my style, but the set of options provided is possibly biased). Part of the limitation of CWEB lies in the fact that the actual typesetting is relagated to TeX, and some decisions can therefore not be made automatically. In particular, while CWEAVE produces typeset code that will adapt to the page width unknown to it (with TeX breaking lines if necessary), this can only be done using paragraph-style formatting (you cannot for instance get braces that normally line up vertically, but will automatically revert to horizontal alignment if the page is wide enough). > 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. > >To those who, like myself, believe that > >certain behaviour simply cannot be achieved by a generic system, and > >require a specialised tool that tackles the problem directly > > Please tell us more about what sorts of things can be done in CWEB > that can't be done in a generic system. One of the experiments in > noweb was to see if specialized tools could be implemented as noweb > filters, while keeping the basic machinery intact. I am always > curious about the viability of this approach. It is of course difficult to prove that something cannot be done in a generic system; the relevant question is whether it can be done easily (if some tool in the toolbox would be as complicated as a specialised program, little has been won). As for fundamental limitations of noweb, I am to unaware of its execution model to answer this. (A vague impression is that its line-orientedness might be a limitation. Noweb appears to transform a file into a sequence of records, each corresponsding to a single line of the source file; I recall that inline expressions in documentation chunks that were split across source file lines behaved curiously.) One very simple and useful feature of CWEBx is that CTANGLE will protest when the body of a module or macro has unbalanced braces or parentheses. Whenever it does, it saves me lots of time I would have to spend otherwise tracing weird syntax error that would appear in the strangest places. The nice thing about this feature is that it was so simple to implement, only about a dozen of statements in C, since CTANGLE was already doing all the necessary preparations (lexing the tokens, and testing for special cases). The same functionality could of course be achieved by a filter in noweb, but it would be much harder to implement, and it would require a separate pass over the file in each tangling operation. Practically, I think that prettyprinting in noweb is limited to things that can be done by lexical means (but please correct me). This means automatic indentation like in CWEB is impossible. Even for those who believe the programmer is the best judge of line breaks and indentation, there are still a few things that cannot be done (easily) by lexical means, for instance discriminating monadic and dyadic uses of the same operator (TeX's math mode has this restriction, and it wouldn't set $**p$ properly, so CWEAVE has to insert hints). 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. It seems that mCWEB adds some C-specific features for organising multi-file projects, like automatic generation of interfacing header files; this might be difficult in a generic system, if you want to do it reliably (not making assumptions about structure of the source code). If there are things that require information that is present in different phases of processing, this would involve more of a headache to implement using simple filters than in one integrated program. 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). I hope this gives some indication of what I hinted at. Marc van Leeuwen 29-Mar-1998 8:40:06-GMT,3830;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 BAA07420 for ; Sun, 29 Mar 1998 01:40:06 -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; Sun, 29 Mar 1998 02:38:06 EST From: Dan Schmidt Reply-To: LitProg@SHSU.edu, dfan@harmonixmusic.com Subject: Re: Literate Programming systems diversity Date: 27 Mar 1998 22:06:19 GMT Message-ID: <6fh7sr$obn$1@murdoch.acc.Virginia.EDU> To: LitProg@SHSU.edu 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. | Practically, I think that prettyprinting in noweb is limited to things | that can be done by lexical means (but please correct me). This means | automatic indentation like in CWEB is impossible. Even for those who | believe the programmer is the best judge of line breaks and indentation, | there are still a few things that cannot be done (easily) by lexical | means, for instance discriminating monadic and dyadic uses of the same | operator (TeX's math mode has this restriction, and it wouldn't set | $**p$ properly, so CWEAVE has to insert hints). dpp does indeed use the programmer's indentation and line-breaks. To me, this is a feature (and I'm not even anti-pretty-printing, like Norman :). It does assume that you the programmer write code fairly neatly, and that you don't expect the typesetter to compensate for sloppy-looking code. As you point out, its spacing can get tricked a little by interesting uses of punctuation. I don't consider that very important, but I can believe that some people do. | 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. In your noweb file, you explicitly list the typedef and class words that you want to be pretty-printed (unfortunately, the sample file I referenced above doesn't have any typedefs, so you can't see it in action). I firmly believe that this is the correct solution. For starters, the pretty-printer doesn't have to go hunting through system libraries looking for classes and typedefs. You can also use weird macros to define things without worrying whether the pretty-printer will catch it (whether using weird macros is a good idea can be discussed another time :). -- 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/ 29-Mar-1998 20:02:48-GMT,4344;000000000001 Received: from math.ams.org (math.ams.org [130.44.210.14]) by csc-sun.math.utah.edu (8.8.5/8.8.5) with SMTP id NAA18664 for ; Sun, 29 Mar 1998 13:02:46 -0700 (MST) Received: from axp14.ams.org by math.ams.org via smtpd (for csc-sun.math.utah.edu [128.110.198.2]) with SMTP; 29 Mar 1998 20:02:41 UT Received: from gate1.ams.org by AXP14.AMS.ORG (PMDF V5.1-8 #1) with SMTP id <01IV8Q7HOHJK000CBG@AXP14.AMS.ORG> for Beebe@Math.Utah.edu; Sun, 29 Mar 1998 14:38:57 EST Received: from kralle.zdv.Uni-Mainz.DE ([134.93.8.158]) by gate1.ams.org via smtpd (for axp14.ams.org [130.44.1.14]) with SMTP; Sun, 29 Mar 1998 19:38:46 +0000 (UT) Received: (from Ufrank@localhost) by kralle.zdv.Uni-Mainz.DE (8.8.8/8.8.8) id VAA07377 for tex-implementors@MATH.AMS.ORG; Sun, 29 Mar 1998 21:38:45 +0200 (MET DST) Received: (from latex3@localhost) by frank.zdv.uni-mainz.de (8.6.9/8.6.9) id UAA24120; Sun, 29 Mar 1998 20:35:50 +0200 Date: Sun, 29 Mar 1998 20:35:50 +0200 From: Frank Mittelbach Subject: debugging formats in web2c To: tex-implementors@ams.org Errors-to: tex-implementors-request@ams.org Message-id: <199803291835.UAA24120@frank.zdv.uni-mainz.de> X-Authentication-warning: kralle.zdv.Uni-Mainz.DE: Ufrank set sender to latex3 using -f Hi everybody, the web2c change file contains an interesting function called print_csnames for some time which unfortunately is not accessible unless you add a new commandline option. it goes like this: ---------------------------------------- @ When debugging a macro package, it can be useful to see the exact control sequence names in the format file. For example, if ten new csnames appear, it's nice to know what they are, to help pinpoint where they came from. (This isn't a truly ``basic'' printing procedure, but that's a convenient module in which to put it.) @ = procedure print_csnames (hstart:integer; hfinish:integer); var c,h,where:integer; begin write_ln (stderr, 'fmtdebug:csnames from ', hstart, ' to ', hfinish, ':'); for h := hstart to hfinish do begin if text (h) > 0 then begin {if have anything at this position} where := h; repeat for c := str_start[text (where)] to str_start[text (where) + 1] - 1 do begin put_byte (str_pool[c], stderr); {print the characters} end; write_ln (stderr, ''); where := next (where); until where = 0; end; end; end; @ Are we printing extra info as we read the format file? @ = @!debug_format_file: boolean; --------------------------------------------- as far as i know (from some old mails) Karl intended to have this function accessed via a command line switch, eg -debug-format so that it would be possible to get a list of a macros being defined in a format. i think this would be a very valid additional debugging aid and i would suggest that this command line option is added to the next release, eg { "progname", 1, 0, 0 }, { "version", 0, 0, 0 }, #ifdef TeX + { "debug-format", 0, (int *) &debugformatfile, 1 }, #ifdef IPC however, even better (in my eyes) would be to have this functionality at the TeX programming level as often when programming dynamic data structures it would be very helpful to get such snapshots of the macros newly created during processing for complicated debugging situations. perhaps when using this command line option one could also make available a new primitive that has the appropriate effect. but even with the current functionality, ie with the above interface this would be a very helpful function. in any case i would vote for a small change: instead of write_ln (stderr, ''); one better has write_ln (stderr, '|'); so that each csname is ended in | to clearly identify csnames which end in spaces (at least for LaTeX formats this would be very helpful --- the spaces are in the output but spaces are difficult to see :-) finally i have a question to the experts: do you see anything wrong with the function and its usage in the tex.ch change file? because when i ran this against the latex format i found that a number of command names, such as downbracefill or @sharp etc etc appeared several times (something which sort of surprised me) comments? frank 29-Mar-1998 20:40:08-GMT,1263;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 NAA19311 for ; Sun, 29 Mar 1998 13:40: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; Sun, 29 Mar 1998 14:20:30 EST From: Alan Shutko Reply-To: LitProg@SHSU.edu, ats@acm.org Subject: Re: Literate Programming systems diversity Date: 29 Mar 1998 20:19:16 GMT Message-ID: <6fmac4$d5e$1@elna.ethz.ch> To: LitProg@SHSU.edu >>>>> "N" == Norman Ramsey writes: N> It has burned me for some time that nobody has extended TeX with N> Derek Oppen's algorithm for finding indentation and line breaks. N> Oppen's model is much better for setting code than the TeX N> algorithm. Is this algorithm of any use for text, or is it just good at code? If it's good for text, you might suggest it to the e-TeX group. Otherwise, it could be done in a filter or macro package. -- Alan Shutko - By consent of the corrupted You have an unusual understanding of the problems of human relationships. 29-Mar-1998 23:52:50-GMT,1040;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 QAA00753 for ; Sun, 29 Mar 1998 16:52:48 -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; Sun, 29 Mar 1998 17:45:58 EST From: ijamz2277l@aol.com (IJAMZ2277l) Reply-To: LitProg@SHSU.edu, ijamz2277l@aol.com Subject: PLEASE HELP ME !! I NEED AN EXE TEXT EDITOR !! Date: 29 Mar 1998 23:41:43 GMT Message-ID: <1998032923414300.SAA13810@ladder01.news.aol.com> To: LitProg@SHSU.edu I HAVE LOOKED AND LOOKED FOR A SIMPLE PROGRAM THAT OPENS A WINDOWS EXE AND ALLOWS ME TO MANUALLY MODIFY IT AND THEN SAVE THE EXE AS I HAVE MODOFIED IT..... CAN SOMEONE HELP ME??? PLEASE..... IF ANYONE KNOWS ANYTHING ABOUT A PROGRAM, I WOULD LOVE TO HEAR FROM YOU.... PLEASE EMAIL ME AT IJAMZ2277L@AOL.COM THANK YOU IN ADVANCE, JAMZ 30-Mar-1998 2:23:20-GMT,4363;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 TAA03474 for ; Sun, 29 Mar 1998 19:23:19 -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; Sun, 29 Mar 1998 20:19:01 EST From: ptjm@interlog.com (Patrick TJ McPhee) Reply-To: LitProg@SHSU.edu, ptjm@interlog.com Subject: Re: Literate Programming systems diversity Date: 28 Mar 1998 20:19:26 GMT Message-ID: <6fjm0e$qrh$1@murdoch.acc.Virginia.EDU> To: LitProg@SHSU.edu In article <6fe4sh$oq$1@murdoch.acc.Virginia.EDU>, Balasubramanian Narasimhan wrote: % I view the diversity of lp systems as striking illustrations of the % fecundity of Don's LP idea. Perhaps. It's also an indication of its audience. A disproportionate number of people to whom LP applies as a concept are willing to implement their own tools either because the existing tools don't satisfy their needs, or because they want to experiment % I vaguely recall, perhaps in the same % interview that Marc van Leeuwen mentions, how Don was disappointed % that the original TeX macro language was not extended What I've heard is that Knuth was (is?) disappointed that more people haven't extended tex, the program, by adding whatsits or whatever, to create specialised typesetting applications. He had expected there to be a lot more work derived from that particular program. I think that literate programming is going to become more popular, but I don't really think it will aquire the sort of caché object-oriented programming has, for instance. Still, the gestation periods for these sorts of things can be quite long. OOP took, say, 20 years before it started catching on. LP might take as long or longer. As I see it, trends in programming tend to evolve like this: Manager: Our people are not productive. Why are they not productive? Sycophant: They are not able to re-use their code from one project to another. We must get tools to allow code re-use. M: Are there such tools? S: Yes, object oriented programming systems will allow us to re-use our code, achieving untold levels of productivity and wealth. M: Yes, I have heard of such things. Let us get them. Which is followed by a period in which everyone cheerfully expects to become more productive, and then they don't. And so a new trend develops. M: Our people are not productive. Why did the object oriented programming system not make them productive? S: We have used this system, and we have created our classes, but we have not documented. We must get a documentation system which will allow us to document our classes, which will allow us to re-use our code, achieving untold levels of productivity and wealth. M: I have heard of such things... Which I think is the current trend. I don't really think this kind of documentation is going to solve problems, because the underlying trouble facing most software development is that the programs haven't been all that well thought-out in the first place, so layering on documentation once you're done isn't likely to help very much. LP does address the real problem, because it encourages the programmer to think about the design of the program and explain it. This is why I use it. It could happen that one day the Sycophant will tell the Manager that the reason people are unproductive is they are working with poor designs, and the solution is for everybody to think things through, and it could be that the Manager will be willing to forgoe milestone demonstrations for the first few months of a project to allow time for design and experimentation, but I don't think enough people will do that for LP to become a real trend. On the other hand, if someone can come up with an LP system which is compelling to a large segment of the industry for some reason, it could take off quickly. This will never happen if people don't continue to fiddle with the existing systems, adding new capabilities and doing things in different ways. There's a lot to be said for doing things differently, just for the sake of being different. -- Patrick TJ McPhee East York Canada ptjm@interlog.com 30-Mar-1998 4:01:55-GMT,2180;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 VAA05185 for ; Sun, 29 Mar 1998 21:01:53 -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; Sun, 29 Mar 1998 21:57:45 EST From: Yann Kieffer Reply-To: LitProg@SHSU.edu, Yann.Kieffer@imag.fr Subject: Re: Literate Programming systems diversity Date: 27 Mar 1998 14:56:31 GMT Message-ID: <6fgemv$8q9$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 > >> On the other hand, to quote Michael Plass, "Don tried very hard not to > >> make TeX a programming language, and he almost succeeded." I don't > >> know many people who fully understand its `digestive' model of > >> execution. > > > >You don't need that kind of knowledge if you're not designing > >big macro packages. > > You need that kind of knowledge if you care about where the ink lands > on the page. And if you don't care, why use TeX? (Half-facetious; > there are other reasons to use TeX.) Well, you can use LaTeX without knowing all the internals of TeX - and when you use LaTeX, you're not using anything else than TeX! You just didn't design the macros yourself; which is what I proposed. What's so good with TeX, as compared to wysiwyg systems, is the fact (as stressed at the beginning of the TeXBook) that knowing how it looks like is not important; you just have to express things properly and TeX will handle most of the work for you. You definitely don't need to know TeX to use it: you just need a suitable macro package for what you're doing, and enough background to use this package. Knuth probably expected to see more macro packages than you can find nowadays. That's the way things evolved, and it's a consequence of the society, and of course on a second level, of TeX internals' complexity. But it's not a feature of TeX. Yann 30-Mar-1998 8:57:04-GMT,1837;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 BAA11052 for ; Mon, 30 Mar 1998 01:57: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; Mon, 30 Mar 1998 02:53:47 EST From: Yann Kieffer Reply-To: LitProg@SHSU.edu, Yann.Kieffer@imag.fr Subject: Re: Literate Programming systems diversity Date: 30 Mar 1998 08:32:58 GMT Message-ID: <6fnlbq$mqe$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 think the only hope of getting really good, useful cross-reference > for programs upwaurds of 10,000 lines is to get the compiler to > compute exact cross-reference and get the LP tool to exploit it. > I think this is the most important open problem in the design of LP > tools. In particular, it's what's keeping HTML browsing of big codes > from being really useful. And if the compiler expresses > cross-refernce as relatinos between source-code locations, there's no > problem making it language-independent. > Hackers, take note... > > Norman This is a nice project... gcc could be extended to achieve such tasks, if there's not already an option doing it. And if you manage to convince Richard Stallman to do LP, then you're pretty sure people will hear about it (GNU has difficulty documenting their software anyway...) Just wait for the moment when Richard will ask people to help rewriting everything with some new "standard" LP tool... Ok, I stop! -- Yann homepage at http://www.geocities.com/Paris/Metro/1018/ 30-Mar-1998 12:10:29-GMT,5765;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 FAA14400 for ; Mon, 30 Mar 1998 05:10:27 -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; Mon, 30 Mar 1998 05:57:54 EST From: Marc van Leeuwen Reply-To: LitProg@SHSU.edu, maavl@zenon.univ-poitiers.fr Subject: Re: Literate Programming systems diversity Date: 30 Mar 1998 11:32:59 GMT Message-ID: <6fnvtb$qcf$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: > > ... while CWEAVE produces typeset code that > >will adapt to the page width unknown to it (with TeX breaking lines if > >necessary), this can only be done using paragraph-style formatting (you > >cannot for instance get braces that normally line up vertically, but > >will automatically revert to horizontal alignment if the page is wide > >enough). > > It has burned me for some time that nobody has extended TeX with Derek > Oppen's algorithm for finding indentation and line breaks. Oppen's > model is much better for setting code than the TeX algorithm. I agree, and inside TeX is the only place you can do it, since the decisions are based upon things like page width and character dimensions that are not know elsewhere. As far as I recall from Oppen's description, it assumes fixed character widths, so it might be slightly non-trivial to adapt into TeX's setting. But maybe one could just take the scaled point (1/65536 of 1/72.27 of an inch, the unit measure for TeX's fixed-point dimension calculations) as a unit for the calculations, and the algorithm would work. An interesting question is whether it can be done (easily) within TeX's macro language, or that it requires a modified TeX. > > >As for fundamental limitations of noweb, > >I am to unaware of its execution model to answer this. (A vague > >impression is that its line-orientedness might be a limitation...) > > I can answer this one :-) Noweb's model is line-oriented only in the > sense that the current TeX back ends preserve line breaks. Excuse my complete ignorance of noweb organisation (for some reason it doesn't stick well in my memory, although I am certain I have tried to look into it several times). But doesn't your statement imply that the front end and all filters also preserve the line structure of the source file? (I am not saying the line structure is preserved in the final document, which is obviously not so for documentation chunks; what I am saying is it seems that no filter can transform source information that is spread across several lines of the source file into something that will occupy a different number of lines in the generated (La)TeX file). > >One very simple and useful feature of CWEBx is that CTANGLE will protest > >when the body of a module or macro has unbalanced braces or parentheses. > >Whenever it does, it saves me lots of time I would have to spend > >otherwise tracing weird syntax error that would appear in the strangest > >places. The nice thing about this feature is that it was so simple to > >implement, only about a dozen of statements in C, since CTANGLE was > >already doing all the necessary preparations (lexing the tokens, and > >testing for special cases). The same functionality could of course be > >achieved by a filter in noweb, but it would be much harder to implement, > >and it would require a separate pass over the file in each tangling > >operation. > > I don't know that it would be so hard to implement---you would need a > lexer and then the rest would be trivial. But lexing C is easy; you > can steal a lexer and roll your own. I didn't say very hard, just harder than adding a few statements in C. > Why is a separate pass a problem? Mainly because people would consider it a waste of time for something that is not productive, and would omit it; the main point of the feature is that it is always active, especially when your are not thinking about it at all (so it catches your errors before the compiler complains). How many people rigged their makefiles so that 'lint' was always run before calling the C compiler? (This refers to the pre-ANSI days; of course with better C compilers, this is no longer required, and the compiler will detect the errors itself; a much more satisfactory situation, which is precisely the point I wanted to make.) > >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; > > This seems pretty useful. How do you know what header files to look > at? Do you look in /usr/include? For CWEBx, as follows. Firstly, '#include' is replaced by '@h' (much like '#define' is replaced by '@d' in CWEB), so that CWEAVE knows which files to look for. Second, for files that reside outside the current directory, a '-I' command line option is provided, as it is for most C compilers (unfortunately most compilers also have a compiled-in search path, which is a bit difficult for users to track; however, for standard header files in C, all relevant identifiers are known to CWEAVE without need for searching). The -I option is useful for instance to locate the standard header files when programming under X, which defines an incredible number of typedef identifiers; somewhat to my surprise (because the system is imperfect, ignoring for instance '#ifdef's) it works well in practice without excessive time consumption. Marc van Leeuwen 30-Mar-1998 14:44:08-GMT,1278;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 HAA17183 for ; Mon, 30 Mar 1998 07:44: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; Mon, 30 Mar 1998 08:35:09 EST From: Norman Ramsey Reply-To: LitProg@SHSU.edu, nr@cs.virginia.edu Subject: Re: Literate Programming systems diversity Date: 30 Mar 1998 14:08:02 GMT Message-ID: <6fo902$2g3$1@murdoch.acc.Virginia.EDU> To: LitProg@SHSU.edu In article <6fnlbq$mqe$1@murdoch.acc.Virginia.EDU>, Yann Kieffer wrote: >> I think the only hope of getting really good, useful cross-reference >> for programs upwaurds of 10,000 lines is to get the compiler to >> compute exact cross-reference and get the LP tool to exploit it. > >This is a nice project... gcc could be extended to achieve >such tasks, if there's not already an option doing it. Getting the info out of the compiler is the easy part (I would use lcc). The hard part is figuring out how to use it and what to rebuild when files change. N 30-Mar-1998 14:46:49-GMT,1766;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 HAA17227 for ; Mon, 30 Mar 1998 07:46:48 -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; Mon, 30 Mar 1998 08:30:10 EST From: Norman Ramsey Reply-To: LitProg@SHSU.edu, nr@cs.virginia.edu Subject: Re: Literate Programming systems diversity Date: 30 Mar 1998 14:05:30 GMT Message-ID: <6fo8ra$2ed$1@murdoch.acc.Virginia.EDU> To: LitProg@SHSU.edu In article <6fmac4$d5e$1@elna.ethz.ch>, Alan Shutko wrote: >>>>>> "N" == Norman Ramsey writes: > >N> It has burned me for some time that nobody has extended TeX with >N> Derek Oppen's algorithm for finding indentation and line breaks. >N> Oppen's model is much better for setting code than the TeX >N> algorithm. > >Is this algorithm of any use for text, or is it just good at code? If >it's good for text, you might suggest it to the e-TeX group. >Otherwise, it could be done in a filter or macro package. Oppen's algorithm is a dynamic-programming algorithm for choosing indentation and line breaks. I can't imagine it would be of much use for text. It requires full knowledge of the widths of all the hboxes on the page, and in the prsence of math formulae would be very hard to do in a filter or macro package---you would essentially have to duplicate all of the code in TeX for finding the natural widths of things. Whereas it would be fairly easy to drop in a new line-breaking algorithm into the source for TeX itself. N 31-Mar-1998 2:28:25-GMT,2972;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 TAA13572 for ; Mon, 30 Mar 1998 19:28:19 -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; Mon, 30 Mar 1998 20:24:26 EST From: amoroso@mclink.it (Paolo Amoroso) Reply-To: LitProg@SHSU.edu, amoroso@mclink.it Subject: How to organize analysis, design and implementation documentation Date: 31 Mar 1998 02:06:37 GMT Message-ID: <6fpj3d$go$1@news.interlog.com> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit To: LitProg@SHSU.edu [NOTE FOR THE MODERATORS: A few days ago I posted with my newsreader to comp.programming.literate the message included below. Since my ISP has recently upgraded the NNTP server, I suspect that there may be problems with the way it handles moderated groups (I experienced posting losses with another moderated group). If you correctly received my message, I apologize - Paolo Amoroso] What are the most useful, versatile or interesting ways of organizing analysis, design and implementation documentation in a literate program? Is it worth including part or all of this material in the first place? I can think of two main orthogonal approaches. The first one, which may be defined "depth-first", consists in discussing analysis, design and implementation issues for each major subsystem, module or program element. It is illustrated by the following outline: Subsystem/Module/Element 1 Analysis issues Design issues Implementation issues (code chunks probably belong here) ... Subsystem/Module/Element n Analysis issues Design issues Implementation issues (code chunks probably belong here) The other organizational scheme, which may be defined "breadth-first", presents separate discussions of analysis, design and implementation issues: Analysis Subsystem/Module/Element 1 issues ... Subsystem/Module/Element n issues Design Subsystem/Module/Element 1 issues ... Subsystem/Module/Element n issues Implementation (code chunks probably belong here) Subsystem/Module/Element 1 issues ... Subsystem/Module/Element 1 issues Of course, since literate programming tools support a flexible order of elaboration, the order of presentation of susbsystems/modules is determined by the best way of explaining the system to the reader. The depth-first scheme seems best suited for providing an in-depth description of each subsystem, while the breadth-first one gives the big picture first. I am a novice and I would appreciate any comment, opinion or information about the above mentioned organizational approaches and other possible ones suggested by your experience. Thanks in advance. Paolo -- Paolo Amoroso 31-Mar-1998 2:28:25-GMT,3966;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 TAA13573 for ; Mon, 30 Mar 1998 19:28:19 -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; Mon, 30 Mar 1998 20:24:30 EST From: Francky Leyn Reply-To: LitProg@SHSU.edu, Francky.Leyn@esat.kuleuven.ac.be Subject: noweb language independance Date: 31 Mar 1998 02:07:37 GMT Message-ID: <6fpj59$hu$1@news.interlog.com> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit To: LitProg@SHSU.edu Hello, 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'm solving this using a LaTeX DSC (Document Structuring Conventions). Making a script executable is done with the LaTeX comment %unix chmod +x filename. A noweb filter extracting these instructions, executes the commands after the tangling phase. This could also be achieved by executing a script that is build up within the literate programming source, removing it in the weaving fase with the elide filter. I prefer the LaTeX DSC way because it needs less typing. 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. I have no solution for this. It could be done through LaTeX DSC or based on the extension of the code chunk. 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. 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 and one must be able to specify wether a chunk is executable or not. Hoping to initiate/triger a discussion on this topic, Best regards, Francky _____________________________________________________________________________ Francky Leyn URL: http://www.esat.kuleuven.ac.be/~leyn/ K.U.Leuven - ESAT MICAS E-mail : Francky.Leyn@esat.kuleuven.ac.be Kardinaal Mercierlaan 94 - 91.21 Tel : ++32 - (0)16 32.10.85 __o B-3001 Heverlee - Belgium Fax : ++32 - (0)16 32.19.75 \<, ____________________________________________________________________()/ ()__ 31-Mar-1998 10:41:22-GMT,5740;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 DAA13520 for ; Tue, 31 Mar 1998 03:41: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; Tue, 31 Mar 1998 04:33:18 EST From: Norman Ramsey Reply-To: LitProg@SHSU.edu, nr@cs.virginia.edu Subject: Re: Literate Programming systems diversity Date: 29 Mar 1998 04:10:01 GMT Message-ID: <6fkhip$97v$1@murdoch.acc.Virginia.EDU> To: LitProg@SHSU.edu In article <6fgj2b$bi0$1@murdoch.acc.Virginia.EDU>, Marc van Leeuwen wrote: >> I think the real complexity of CWEB comes from mixing functions that >> should be kept separate. In particular, from putting typesetting >> commands in the code, and from trying to control the prettyprinter. > >I am not sure I understand what you mean by complexity. I think I'm talkuing about `cognitive complexity', or difficulty of use. Many people just seem to have a hard time understanding how to edit their code once it is full of typesetting commands. One loses separation of concerns, which is a good way to manage a big set of features. >I think that if automatic formatting would really be reliable, and allow >some flexibilty in choosing the layout style (and indeed this should not >happen inside the code, but globally, for instance on the command line), >then you would in fact need to spend considerably less time on >formatting. With Spidery Web, we found that giving people flexibility in choosing the layout style meant that they spent inordinate amounts of time fiddling with their layout style. Perhaps we gave them too much flexibility. > ... while CWEAVE produces typeset code that >will adapt to the page width unknown to it (with TeX breaking lines if >necessary), this can only be done using paragraph-style formatting (you >cannot for instance get braces that normally line up vertically, but >will automatically revert to horizontal alignment if the page is wide >enough). It has burned me for some time that nobody has extended TeX with Derek Oppen's algorithm for finding indentation and line breaks. Oppen's model is much better for setting code than the TeX algorithm. >As for fundamental limitations of noweb, >I am to unaware of its execution model to answer this. (A vague >impression is that its line-orientedness might be a limitation. Noweb >appears to transform a file into a sequence of records, each >corresponsding to a single line of the source file; I recall that inline >expressions in documentation chunks that were split across source file >lines behaved curiously.) I can answer this one :-) Noweb's model is line-oriented only in the sense that the current TeX back ends preserve line breaks. Moreover, many of the 3rd-party prettyprinters also happen to preserve the user's indentation and line breaks (changing only the fonts). This is not a fundamental limitation of noweb, however---in fact, the l2h filter, which converts LaTeX to HTML, is perfectly happy converting LaTeX constructs that are split across lines. >One very simple and useful feature of CWEBx is that CTANGLE will protest >when the body of a module or macro has unbalanced braces or parentheses. >Whenever it does, it saves me lots of time I would have to spend >otherwise tracing weird syntax error that would appear in the strangest >places. The nice thing about this feature is that it was so simple to >implement, only about a dozen of statements in C, since CTANGLE was >already doing all the necessary preparations (lexing the tokens, and >testing for special cases). The same functionality could of course be >achieved by a filter in noweb, but it would be much harder to implement, >and it would require a separate pass over the file in each tangling >operation. I don't know that it would be so hard to implement---you would need a lexer and then the rest would be trivial. But lexing C is easy; you can steal a lexer and roll your own. Why is a separate pass a problem? >Practically, I think that prettyprinting in noweb is limited to things >that can be done by lexical means (but please correct me). This means >automatic indentation like in CWEB is impossible. This statement is incorrect. In fact, the Pretzel prettyprinters use parsers and do automatic indentation, as far as I know. >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? >... 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). I think the only hope of getting really good, useful cross-reference for programs upwaurds of 10,000 lines is to get the compiler to compute exact cross-reference and get the LP tool to exploit it. I think this is the most important open problem in the design of LP tools. In particular, it's what's keeping HTML browsing of big codes from being really useful. And if the compiler expresses cross-refernce as relatinos between source-code locations, there's no problem making it language-independent. Hackers, take note... Norman 31-Mar-1998 10:43:20-GMT,3466;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 DAA13569 for ; Tue, 31 Mar 1998 03:43:19 -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; Tue, 31 Mar 1998 04:33:14 EST From: Marc van Leeuwen Reply-To: LitProg@SHSU.edu, maavl@zenon.univ-poitiers.fr Subject: Re: How to organize analysis, design and implementation documentation Date: 31 Mar 1998 09:33:28 GMT Message-ID: <6fqd98$hom$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 asked: > What are the most useful, versatile or interesting ways of organizing > analysis, design and implementation documentation in a literate program? Is > it worth including part or all of this material in the first place? Not having much experience with setting up large projects as a literate program myself (what I have done is studing/modifying existing literate programs as well converting existing illiterate programs), I can only give a suggestion that I would hope to be useful. This suggestion is: start writing down the big picture you have of the project before starting its implementation, and describe as best you can the reasons for envisioning the need for certain subsystems/modules. This is not because I think this description will actually become the root of your final literate program; for my own projects I would tend to be pessimistic, and not expect that the original ideas would correspond very acurately to the eventual design, so that this part would end up to be completely rewritten. (I think it is more important that a literate program presents a coherent description of its current state, than that it faithfully reflects its own conception and history.) But by starting with this overall picture, you at least ensure that you do give some thought about explaining it, and besides, you will be reminded yourself about how you viewed the program before it actually existed. 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. One reason probably is that there is little actual code that corresponds to it. If your program uses carefully designed data structures, these provide an opportunity to elaborate on general design considerations, but this does not always suffice. In fact, even for the prime example of literate programming, the program TeX, Knuth does not give much clues as to why certain crucial decisions were made (why were certain algorithms selected to be primitive in TeX, and others not; why was TeX's language designed as it is?) Some interesting complements to the program are given in the paper "The errors of TeX", but it is quite disjoint from the TeX program. Marc van Leeuwen 31-Mar-1998 15:48:17-GMT,1213;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 IAA21581 for ; Tue, 31 Mar 1998 08:48:14 -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; Tue, 31 Mar 1998 09:31:46 EST Message-ID: <35210C59.54BBE34A@objectint.com> From: "Eric S. Paro" Reply-To: LitProg@SHSU.edu, ericp@objectint.com MIME-Version: 1.0 Subject: Seeking Smalltalk Pros for Open Positions in the USA!!! Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit Date: Tue, 31 Mar 1998 15:29:47 GMT To: LitProg@SHSU.edu Please pardon the intrusion to the group, but we need to hire additional Smalltalk programmers/developers. Please see our post in misc.jobs.contract, misc.jobs.offered or triangle.jobs. If you don't have access to those groups, please contact: ObjectIntelligence Corporation 900 Ridgefield Drive, Suite 240 Raleigh,NC 27609 800-789-6595 voice (alternate 919.878.6690) 800-789-0712 fax dianal@objectint.com 31-Mar-1998 17:07:11-GMT,2786;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 KAA24813 for ; Tue, 31 Mar 1998 10:07:10 -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; Tue, 31 Mar 1998 10:47:09 EST From: Dan Schmidt Reply-To: LitProg@SHSU.edu, dfan@harmonixmusic.com Subject: Re: Literate Programming systems diversity Date: 31 Mar 1998 16:24:36 GMT Message-ID: <6fr5c4$svc$1@murdoch.acc.Virginia.EDU> To: LitProg@SHSU.edu zivca@netvision.net.il (Ziv Caspi) writes: | ptjm@interlog.com (Patrick TJ McPhee) wrote: | | > In article <6fe4sh$oq$1@murdoch.acc.Virginia.EDU>, | > Balasubramanian Narasimhan wrote: | | > % I view the diversity of lp systems as striking illustrations of | > % the fecundity of Don's LP idea. | | > Perhaps. It's also an indication of its audience. A | > disproportionate number of people to whom LP applies as a concept | > are willing to implement their own tools either because the | > existing tools don't satisfy their needs, or because they want to | > experiment | | Allow me to add a third POV: The abundance of LP systems out there | is because none of them is a ``winner''. | | We all know a winner when we see one: TeX, Ghostview, dvips, | etc. are all winners. They are so much better than their peers that | no one uses the competition. (Also, they are so useful that people | actually use them; However, whether LP is *that* useful or not is an | altogether another issue.) I switched from CWEB to noweb (after briefly trying Funnelweb) precisely because it seemed to be the "winner". It seems to me to be clearly the front-runner in LP systems today, certainly for multi-language programming and arguably for C/C++ as well (many people still use CWEB or a variant thereof; I didn't like its flat document structure and the way it thought it knew better than me how to do things like indent and choose keywords). noweb also brilliantly avoids the problems introduced by Patrick's observation (that many LP'ers seem to want to hack their own system) by letting them easily hack directly into the noweb pipeline. The only thing I didn't like about noweb was the lack of a good (IMO) pretty-printer; so I wrote one and added it in. Problem solved. -- 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/ 31-Mar-1998 18:08:45-GMT,3693;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 LAA27955 for ; Tue, 31 Mar 1998 11:08:40 -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; Tue, 31 Mar 1998 11:22:15 EST From: Norman Ramsey Reply-To: LitProg@SHSU.edu, nr@cs.virginia.edu Subject: Re: Literate Programming systems diversity Date: 30 Mar 1998 15:50:04 GMT Message-ID: <6foevc$7st$1@murdoch.acc.Virginia.EDU> To: LitProg@SHSU.edu In article <6fnvtb$qcf$1@murdoch.acc.Virginia.EDU>, Marc van Leeuwen wrote: >As far as I recall from Oppen's >description, it assumes fixed character widths Oppen's algorithm is trivially extensible to variable widths. I've implented it and it's easy. It really only wants to know widths of hboxes. >Excuse my complete ignorance of noweb organisation (for some reason it >doesn't stick well in my memory, although I am certain I have tried to >look into it several times). But doesn't your statement imply that the >front end and all filters also preserve the line structure of the source >file? (I am not saying the line structure is preserved in the final >document, which is obviously not so for documentation chunks; what I am >saying is it seems that no filter can transform source information that >is spread across several lines of the source file into something that >will occupy a different number of lines in the generated (La)TeX file). Filters are free to derange the line structure of the source program at will. The TeX filters are careful not to, in order that the line numbers in the .tex output be the same as the line numbers in the .nw input, and therefore that error messages from TeX or LaTeX can be referred to the original source file (since TeX has no analog of #line). This behavior is entirely a property of the filters and the TeX back end, not of the noweb architecture. The behavior occasionally causes problems when noweb emits a very long line in order to avoid introducing a spurious newline. On the other hand, the HTML filters make no attempt to preserve line structure, and in fact the l2h filter (for converting LaTeX to HTML) does exactly transform source information that is spread across several lines of the source file into something that will occupy a different number of lines in the generated HTML. >> Why is a separate pass a problem? > >Mainly because people would consider it a waste of time for something >that is not productive, and would omit it; the main point of the feature >is that it is always active, especially when your are not thinking about >it at all (so it catches your errors before the compiler complains). How >many people rigged their makefiles so that 'lint' was always run before >calling the C compiler? (This refers to the pre-ANSI days; of course >with better C compilers, this is no longer required, and the compiler >will detect the errors itself; a much more satisfactory situation, which >is precisely the point I wanted to make.) This is a good point---if I had this problem, I would probably build a separate `ceeweb' out of noweb parts, to make sure the interesting C-dependent stuff always ran. Having to do that is the price one pays for a toolbox approach that supports multiple programming languages. One of the things I hope to do with noweb 3 is lower the run-time cost of having a bunch of filters always included. N -- Norman Ramsey http://www.cs.virginia.edu/~nr 1-Apr-1998 3:08:45-GMT,1695;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 UAA17678 for ; Tue, 31 Mar 1998 20:08:44 -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; Tue, 31 Mar 1998 21:03:37 EST From: zivca@netvision.net.il (Ziv Caspi) Reply-To: LitProg@SHSU.edu, zivca@netvision.net.il Subject: Re: Literate Programming systems diversity Date: 31 Mar 1998 02:07:15 GMT Message-ID: <6fpj4j$hf$1@news.interlog.com> To: LitProg@SHSU.edu ptjm@interlog.com (Patrick TJ McPhee) wrote: > In article <6fe4sh$oq$1@murdoch.acc.Virginia.EDU>, > Balasubramanian Narasimhan wrote: > % I view the diversity of lp systems as striking illustrations of the > % fecundity of Don's LP idea. > Perhaps. It's also an indication of its audience. A disproportionate > number of people to whom LP applies as a concept are willing to implement > their own tools either because the existing tools don't satisfy their > needs, or because they want to experiment Allow me to add a third POV: The abundance of LP systems out there is because none of them is a ``winner''. We all know a winner when we see one: TeX, Ghostview, dvips, etc. are all winners. They are so much better than their peers that no one uses the competition. (Also, they are so useful that people actually use them; However, whether LP is *that* useful or not is an altogether another issue.) -------------------------------- Ziv Caspi zivca@netvision.net.il