Archive-Date: Wed, 01 Feb 1995 15:19:22 CDT Sender: owner-litprog@SHSU.edu From: dynalec@aol.com (DYNALEC) Subject: 8051 Assembler/Simulator Date: 1 Feb 1995 16:04:23 -0500 Message-ID: <3got0n$mb3@newsbf02.news.aol.com> Reply-To: LitProg@SHSU.edu, dynalec@aol.com (DYNALEC) To: LitProg@SHSU.EDU I'm not sure if this is the right newsgroup to ask, but, does anyone know where someone might be able to obtain a cheap (or free) Assembler/Simulator package for an 8051 microcontroller? -Tony ================================================================================ Archive-Date: Wed, 01 Feb 1995 16:49:20 CDT Sender: owner-litprog@SHSU.edu From: weiqigao@crl.com (Weiqi Gao) Reply-To: LitProg@SHSU.edu, weiqigao@CRL.COM Subject: Re: 8051 Assembler/Simulator Date: Wed, 01 Feb 95 16:18:00 CST Message-ID: <3gp1b1$1k8@nntp.crl.com> MIME-Version: 1.0 To: LitProg@SHSU.EDU In article <3got0n$mb3@newsbf02.news.aol.com>, dynalec@aol.com says... > >I'm not sure if this is the right newsgroup to ask, but, does anyone know >where someone might be able to obtain a cheap (or free) >Assembler/Simulator package for an 8051 microcontroller? > >-Tony Hi, Tony, I have sent you the FAQ of this group. Weiqi Gao weiqigao@crl.com ================================================================================ Archive-Date: Wed, 01 Feb 1995 19:56:08 CDT Sender: owner-litprog@SHSU.edu From: przemek@rrdjazz.nist.gov (Przemek Klosowski) Reply-To: LitProg@SHSU.edu, przemek@RRDJAZZ.NIST.GOV Subject: Re: borland or visual c++ ? Date: 01 Feb 1995 22:21:16 GMT Message-ID: To: LitProg@SHSU.EDU In article <3gm2ma$llc@jhunix1.hcf.jhu.edu> gk@vangogh.med.jhu.edu (Gil Kedem) writes: I am about to write c++ software for pc's and I do not know which compiler to use. The program will have nice Windows interfacing, and will involve signal acquisition and some digital signal processing. Does anyone know which is better? Visual C++ or Borland C++? (or maybe something else) From the viewpoint of comp.programming.literate, it does not matter which C++ compiler you use. You may even use Pascal, Basic or Fortran, but the important point is that you MUST use the literate programming style to properly document your program. Please ask in this newsgroup if you want to find out which literate programming tools are best in your situation. -- przemek klosowski (przemek@rrdstrad.nist.gov) Reactor Division (bldg. 235), E111 National Institute of Standards and Technology Gaithersburg, MD 20899, USA (301) 975 6249 ================================================================================ Archive-Date: Wed, 01 Feb 1995 21:20:54 CDT Sender: owner-litprog@SHSU.edu Message-ID: <19950201.183638.624790.NETNEWS@VM1.ULG.AC.BE> Date: Wed, 1 Feb 1995 16:08:01 +0100 Subject: help needed for hp calculator From: Vandelaer OLivier Reply-To: LitProg@SHSU.edu, vandela@GW.UNIPC.ULG.AC.BE To: LitProg@SHSU.EDU My name is Olivier My request is simple : Iwould like to contact people for informations about calculators HP 48 g/gx programming. Some of my questions are : Does it exist some freeware,sharewares...for hp calculator? Does anybody know about a bases language for programming hp calculator? Please I am not a specialist but I would realy like to progress.... Thanks to e-mail me. OLIVIER VDL (biochemistry student) ================================================================================ Archive-Date: Wed, 01 Feb 1995 22:14:06 CDT Sender: owner-litprog@SHSU.edu From: norman@flaubert.bellcore.com (Norman Ramsey) Reply-To: LitProg@SHSU.edu, norman@FLAUBERT.BELLCORE.COM Subject: Clueless questions about literate programming are welcome here Message-ID: Date: Wed, 1 Feb 1995 22:30:10 GMT To: LitProg@SHSU.EDU Some people may have misunderstood an earlier post of mine to be hostile to people who are clueless newbies to literate programming. False, not so. Clueless and all other questions about literate programming are welcome in this newsgroup. The people who are annoying us are the ones who keep asking DOS/Windows programming questions and other things that have nothing to do with literate programming. -- Norman Ramsey norman@bellcore.com ================================================================================ Archive-Date: Thu, 02 Feb 1995 07:51:52 CDT Sender: owner-litprog@SHSU.edu From: FOLSCHEID_b@istvax.ist.lu (Folscheid Bob) Reply-To: LitProg@SHSU.edu, FOLSCHEID_b@ISTVAX.IST.LU Subject: Pascal XSC Date: Thu, 2 Feb 1995 14:36:08 Message-ID: To: LitProg@SHSU.EDU Can anyone send me an FTP,WWW,E-Mail Adress where to find something about Pascal XSC or Pascal SC, Thanks Bob FOLSCHEID (E-Mail: FOLSCHEID_b@ISTVAX.IST.LU please reply me on that address) ================================================================================ Archive-Date: Thu, 02 Feb 1995 07:51:56 CDT Sender: owner-litprog@SHSU.edu From: FOLSCHEID_b@istvax.ist.lu (Folscheid Bob) Reply-To: LitProg@SHSU.edu, FOLSCHEID_b@ISTVAX.IST.LU Subject: Pascal X(SC) Date: Thu, 2 Feb 1995 14:31:18 Message-ID: To: LitProg@SHSU.EDU Can anybody send me an FTP,WWW,E-Mail Adress where to find something about Pascal XSC or Pascal SC, Thanks Bob FOLSCHEID (E-Mail: FOLSCHEID_b@ISTVAX.IST.LU please reply me on that address) ================================================================================ Archive-Date: Thu, 02 Feb 1995 11:47:15 CDT Sender: owner-litprog@SHSU.edu From: schrod@iti.informatik.th-darmstadt.de (Joachim Schrod) Reply-To: LitProg@SHSU.edu, schrod@ITI.INFORMATIK.TH-DARMSTADT.DE Subject: AOL stupidity (was Re: C++ for 486 PC) Date: 2 Feb 1995 11:36:09 GMT Message-ID: <3gqg39$gvv@rs18.hrz.th-darmstadt.de> To: LitProg@SHSU.EDU In article <3gldlc$99v@nntp.crl.com>, weiqigao@crl.com (Weiqi Gao) writes: > > AOL apparantly have a News Group guide which tells their people that > comp.programming.literate is a group for beginning programmers. > > I have been trying to curb these AOL posts for quite some time. If that News Group guide is not only a rumor, but confirmed, could you please post some email address of an AOL official that is responsible for such documents? One could Cc: *all* responses to AOL folks to him (including the FAQ :-). Let's see how long it takes to update that guide... But I would only want to annoy people if it's confirmed that they are connected somehow to the incidents we see here. > And my postings here become another annoyance (apparently to some.) No. I was glad to see that somebody took up the action. > In the next few weeks, I'll try another strategy: mail the FAQ to the sender > of these posts. Good idea, I might do so as well. It takes money for AOLers to read their mail, doesn't it? > YOU CAN'T FIX STUPID. Hmm. ``Nevery ascribe to stupidity what can be equally well be malice.'' Or similar. ;-) Joachim -- =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= Joachim Schrod Email: schrod@iti.informatik.th-darmstadt.de Computer Science Department Technical University of Darmstadt, Germany ================================================================================ Archive-Date: Thu, 02 Feb 1995 13:58:50 CDT Sender: owner-litprog@SHSU.edu Date: Thu, 02 Feb 1995 19:35:00 -0700 (PDT) From: "Stephen Boyan (510) 926-3291/fax 926-3604" Reply-To: LitProg@SHSU.edu, BOYANST@NCAL.KAIPERM.ORG Subject: RE: help needed for hp calculator To: LitProg@shsu.edu > HP Calc sofware sources This is not the place. However, I have heard there is an HPHAND forum on either Compushare or AOL. There is a magazine called The Palmtop Papers that covers the HP Palmtop, a neat little machine, IMHO. ================================================================================ Archive-Date: Thu, 02 Feb 1995 14:32:55 CDT Sender: owner-litprog@SHSU.edu From: sp106@york.ac.uk (Stephen Parker) Reply-To: LitProg@SHSU.edu, sp106@YORK.AC.UK Subject: Re: Looking for:Mathcad 5.0 for Windows Date: 2 Feb 1995 11:10:57 GMT Message-ID: <3gqek1$s1g@castle.york.ac.uk> To: LitProg@SHSU.EDU Paul Dunne (paul@demon.co.uk) wrote: : Stacy Breem (sbreem@pipeline.com) wrote: : : Master of Nothing : : Seer of Nothing : : Now Thats Something! : This is comp.programming.literate - WHY do people insist on posting : irrelevant stuff here? Because they are part of the small number of programmers capable of reading. stephen -- #################################################### # sp106@york.ac.uk # http://www.york.ac.uk/~sp106 # # Each set includes a turntable, nine inch icing # # bag, six high definition nozzles... # #################################################### ================================================================================ Archive-Date: Thu, 02 Feb 1995 15:28:34 CDT Sender: owner-litprog@SHSU.edu From: davis@wln.com (Ryan Davis) Reply-To: LitProg@SHSU.edu, davis@WLN.COM Subject: Re: Clueless questions about literate programming are welcome here Date: Thu, 02 Feb 1995 09:27:30 -0800 Message-ID: To: LitProg@SHSU.EDU In article , norman@flaubert.bellcore.com (Norman Ramsey) wrote: >Some people may have misunderstood an earlier post of mine to be >hostile to people who are clueless newbies to literate programming. >False, not so. Clueless and all other questions about literate >programming are welcome in this newsgroup. The people who are >annoying us are the ones who keep asking DOS/Windows programming >questions and other things that have nothing to do with literate >programming. Good... Then I have a couple of questions: 1) Is there a FAQ? I normally read a newsgroup for more than a month before I start to question this, so... I haven't seen one posted yet... 2) Is Literate programming just a means of pretty printing and automating documentation? 3) Is there any implementations of *WEB* that are macintosh compatible, OR that are machine independant and will run with PERL or some other widely available language? 4) I've noticed several *WEB* thingies are C, C++, Pascal...... literate(?) but never have I seen the word smalltalk... anyone? Hows that? -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- Smalltalk & C++ Programmer \ _O_ / ...will code for food \ | / http://www.wln.com/~davis \ / davis@wln.com -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- ================================================================================ Archive-Date: Thu, 02 Feb 1995 15:54:47 CDT Sender: owner-litprog@SHSU.edu From: dodger@gcr.com (Roger Labbe) Reply-To: LitProg@SHSU.edu, dodger@GCR.COM Subject: Re: REQUEST: Info on Knuth Date: 2 Feb 1995 13:05:05 -0500 Message-ID: <3gr6sh$o87@lute.gcr.com> To: LitProg@SHSU.EDU http://www.clbooks.com/nbb/knuth.html is an interview of Knuth back in 91. he talks about several things, including that he doesn't use email. Read the interview for the reasons. also, he talks about coming out with a monograph as preparation for Vol 4 of The Art of Computer Programming. His book The Stanford Graphbase is a result of that effort (I think published by Addison Wesley, 1993.) Roger ================================================================================ Archive-Date: Thu, 02 Feb 1995 22:49:29 CDT Sender: owner-litprog@SHSU.edu From: wmschalck@aol.com (WMSchalck) Subject: I'm from AOL - Don't flame me yet... Date: 2 Feb 1995 23:11:21 -0500 Message-ID: <3gsad9$da9@newsbf02.news.aol.com> Reply-To: LitProg@SHSU.edu, wmschalck@aol.com (WMSchalck) To: LitProg@SHSU.EDU I have been browsing your news group and have noticed the inappropriate messages from some AOL users. On AOL there is a news group search feature and this is the only one that is listed under computer programming. I can see how a slightly less "literate" person from AOL could be easily confused into thinking this is a discussion of "Literate Programmers" as oposed to "Illerate Programmers" If you will e-mail me the FAQ I will try to find out how to get the AOL description updated so you can live here in peace... Have a nice day! See, not all AOL users are stupid ;) ================================================================================ Archive-Date: Thu, 02 Feb 1995 23:06:23 CDT Sender: owner-litprog@SHSU.edu Date: Thu, 2 Feb 95 23:05:04 CST From: dhein@Onramp.NET Reply-To: LitProg@SHSU.edu, dhein@ONRAMP.NET Subject: RE: I'm from AOL - Don't flame me yet... To: LitProg@SHSU.edu, WMSchalck Message-ID: MIME-Version: 1.0 Content-Type: MULTIPART/MIXED; charset=US-ASCII --- Content-Type: TEXT/PLAIN; charset=US-ASCII Here it is ... thanks for your help ... ---------------Original Message--------------- I have been browsing your news group and have noticed the inappropriate messages from some AOL users. On AOL there is a news group search feature and this is the only one that is listed under computer programming. I can see how a slightly less "literate" person from AOL could be easily confused into thinking this is a discussion of "Literate Programmers" as oposed to "Illerate Programmers" If you will e-mail me the FAQ I will try to find out how to get the AOL description updated so you can live here in peace... Have a nice day! See, not all AOL users are stupid ;) ----------End of Original Message---------- ------------------------------------- Name: Dave Hein E-mail: dhein@onramp.net Date: 02/02/95 Time: 23:05:04 ------------------------------------- --- Content-Type: TEXT/PLAIN; SizeOnDisk=58134; name="LITPROG.TXT"; CHARSET=US-ASCII Content-Description: LITPROG.TXT Path: bloom-beacon.mit.edu!senator-bedfellow.mit.edu!faqserv From: thompson@sun1.coe.ttu.edu Newsgroups: comp.programming.literate,comp.answers,news.answers Subject: comp.programming.literate FAQ Supersedes: Followup-To: comp.programming.literate Date: 16 Jan 1995 10:46:05 GMT Organization: Texas Tech University, Lubbock, Texas, USA Lines: 1543 Approved: news-answers-request@MIT.Edu Distribution: world Expires: 14 Feb 1995 10:45:13 GMT Message-ID: Reply-To: thompson@sun1.coe.ttu.edu NNTP-Posting-Host: bloom-picayune.mit.edu Summary: Literate Programming FAQ--general introduction to the concepts of literate programming and the tools available to write literate programs. X-Last-Updated: 1994/08/23 Originator: faqserv@bloom-picayune.MIT.EDU Xref: bloom-beacon.mit.edu comp.programming.literate:1836 comp.answers:9537 news.answers:33215 Archive-name: literate-programming-faq Last-modified: 1994/08/23 Version: 1.1.10 Welcome to the Literate Programming Frequently Asked Questions List ------------------------------------------------------------------- This version was created Tuesday, August 23, 1994, and should considered stale after 90 days. Information contained in this document is the best available at preparation. The original file was dated October 15, 1993 (just for historical purposes). 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." Copyright 1993, 1994 David B. Thompson. All rights reserved worldwide. Permission is granted to copy this document for free distribution so long as it remains intact and unmodified. For other arrangements, contact the author/maintainer via email: thompson@sun1.coe.ttu.edu. What's New? ----------- + Add Fold2Web entry. + Correct noweb.el entry. (Thanks Dominique!) + Update nuweb.el entry. + Update SchemeWEB entry. + Update WWW and literate programming entry. + Update c2cweb entry. = ====================================================================== * 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, who can be reached at: thompson@sun1.coe.ttu.edu * Preferred mailing address for FAQ related comments/questions. wqdbt@ttacs1.ttu.edu * Forwarded to my pc. Comment and constructive criticism is 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 not be complete for some months. Nevertheless, the information contained herein may be useful to some. Use it as it is intended. - ---------------------------------------------------------------------- - Typography ------------ Major sections of the FAQ are divided by double lines (====). Minor sections and other divisions are separated by single lines (----). Major topics use a "* " as a leader. Minor topics use a "- " as a leader. This should simplify searching for topics. = ====================================================================== Table of Contents: ------------------ * Introduction, or "What's this all about?" - Typography * How do I get the FAQ? - Literate Programming FAQ - FWEB FAQ * Is there a newsgroup? (The comp.programming.literate newsgroup) * What internet nodes are of interest to literate programmers? * What is literate programming? * How do I begin literate programming? * What literate programming tools are available and where are they? - APLWEB - AWEB - CLiP - CWEB - FunnelWeb - FWEB - IMPACT - lit2x - Literate Programmer's Workshop (LPW) - MapleWEB - MWEB (Schrod/Detig) - MWEB (Sewell) - noweb - nuweb - ProTeX - RWEB - SchemeWEB - Spidery WEB - WEB - WinWordWEB * Are there other tools I should know about? - C2LaTeX - c2cweb - c2man - cnoweb - Fold2web - FunnelWeb mode - noweb.el - nuweb.el - TIE - Web mode * What other resources are available? - World Wide Web - TeX Resources - Virtual Coursework * Are there any code examples? - Examples included with developer's tools - Cameron Smith's KR-CWEB - Stanford GraphBase * Bibliographies. * How to anonymously ftp. * Acknowledgements. * End notes. = ====================================================================== * How do I get the FAQ? ----------------------- - 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.") An alternative is to use the fileserver at Sam Houston State University (SHSU). Send a message to FILESERV@SHSU.EDU and include in your message: SENDME LITPROG.FAQ The file server will forward a copy of the file to you via email. - ---------------------------------------------------------------------- - FWEB FAQ ---------- Marcus Speh maintains the FWEB FAQ. The current version number is 1.29. It can be retrieved in the same way as this FAQ; either by anonymous ftp or through the SHSU file server. On the SHSU server, the file name is FAQ.FWEB. Invoke your ftp software, open a connection to NIORD.SHSU.EDU [192.92.115.8], attach to the directory FAQ, and transfer the file FAQ.FWEB. Alternatively, send a message to the file server, FILESERV@SHSU.EDU, and include the following text in a one line message: SENDME FAQ.FWEB The file server will send the current version of the file via email. 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 (LPA) in the directory LPA/Documentation/faq/fweb (see the references to LPA below for more information). Also, Marcus Speh is looking for someone willing to take over the FWEB FAQ. The text of his email message follows... "Please add to the FWEB FAQ the note that I am looking for someone to take the maintenance of the FAQ over - I am ready to assist in any way whatsoever, including tons of mail, notes for v1.29->v1.30, Texinfo sources, a WWW server and Hypertextification etc." If you're interested, send mail to marcus@x4u2.desy.de and express your willingness to serve. = ====================================================================== * Is there a newsgroup? ----------------------- One of the most important resources is the literate programming newsgroup, comp.programming.literate. You can read this newsgroup using your standard reader. Altenatively, the newsgroup is gated to a mailing list hosted by George Greenwade and Sam Houston State University. You can subscribe by sending mail to the list-server, LISTSERV@SHSU.EDU, and include in the message one line of text: SUBSCRIBE LITPROG "your name in quotes" The list is unmoderated; messages sent to litprog@shsu.edu are automatically distributed to all subscribers and cross-posted to comp.programming.literate. Archives of the mailing list and newsgroup are maintained on niord.shsu.edu [192.92.115.8] in the directory litprog. = ====================================================================== * 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. The CTAN sites are: ftp host IP CTAN root Institution and Sponsor ------------------------------------------------------------------------- ftp.tex.ac.uk 134.151.79.32 pub/archive Aston Univ./UK TeX U.G. ftp.dante.de 129.206.100.192 soft/tex DANTE e.V. ftp.shsu.edu 192.92.115.10 tex-archive Sam Houston State Univ. Other nodes and directories of interest include: Node: niord.shsu.edu [192.92.115.8] Directory: various (do some snooping!) Notes: Has a gopher server. 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/ = ====================================================================== * 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 programmer, who wants to provide the best possible documentation 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 document such a program we want to explain each individual part of the web and how it relates to its neighbours. The typographic 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 combining the two, we can develop a style of programming that maximizes our ability to perceive the structure of a complex piece of software, and at the same time the documented programs 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 = ====================================================================== * 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. = ====================================================================== * What literate programming tools are available and where are they? ------------------------------------------------------------------- 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. :-) - ---------------------------------------------------------------------- - 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. - ---------------------------------------------------------------------- - 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. - ---------------------------------------------------------------------- - CLiP ------ Developer: E.W. van Ammers and M.R. Kramer Version: Unknown Hardware: Vax/VMS, Unix, and MS-DOS Languages: Any programming language. Formatter: Any formatter (TeX, LaTeX, Troff, Runoff, etc) or any wordprocessor including WYSIWYG systems (Word Perfect, Win Word, Ami Pro, Word, etc.) Availability: Anonymous ftp from: sun01.info.wau.nl:/CLIP/ms_dos MS-DOS version sun01.info.wau.nl:/CLIP/vax_vms VAX/VMS version CTAN:/web/clip LPA:/machines/ms-dos LPA:/machines/vax Readme: With bundle above Description: CLiP does not use explicite commands to perform the extraction process. Rather it recognizes pseudostatemens written as comments in the programming language in question. CLiP distinguishes pseudostatments from ordinary comments because the former comply with a 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 but we have not yet experimented with this form of documentation. 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 documentatio 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 segements. + 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: ammers@rcl.wau.nl - ---------------------------------------------------------------------- - 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 Note: A fork of CWEB 3.x was developed by Marc van Leeuwen which implements several changes to CWEB. It is available for anonymous ftp from ftp.cwi.nl:pub/cweb. The principle changes are: - Scans include files for typedef definitions - Grammar and formatting rules are well separated, allowing for run-time selection of a rule set (via command line option) - New manual. - ---------------------------------------------------------------------- - 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. - ---------------------------------------------------------------------- - FWEB ------ Developer: John A. Krommes Version: 1.30a (1.40 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: Plain TeX and LaTeX. 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 - ---------------------------------------------------------------------- - 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. - ---------------------------------------------------------------------- - lit2x ------- Developer: Unknown Version: Unknown Hardware: Unknown Languages: Unknown Formatter: Unknown Availability: Anonymous ftp from: LPA:/independent Readme: Unknown Description: None available Support: Unknown - ---------------------------------------------------------------------- - 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. - ---------------------------------------------------------------------- - MapleWEB ---------- Developer: Unknown Version: Unknown Hardware: Unknown Languages: Maple Formatter: Unknown Availability: Anonymous ftp from: LPA:/maple Readme: Unknown Description: None Support: Unknown - ---------------------------------------------------------------------- - 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. - ---------------------------------------------------------------------- - 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. - ---------------------------------------------------------------------- - noweb ------- Developer: Norman Ramsey Version: 2.6 Hardware: Unix and DOS platforms. Languages: All programming languages. Formatter: Plain TeX, LaTeX, and HTML (Mosaic) formatters. Availability: Anonymous ftp from: CTAN:/web/noweb LPA:/independent DOS version also in LPA:/machines/ms-dos also bart.kean.edu:/pub/leew Last recourse, use bellcore.com:/pub/norman Readme: With bundle above. Description: noweb is designed to meet the needs of literate programmers while remaining as simple as possible. Its primary advantages are simplicity, extensibility, and language-independence. noweb uses 5 control sequences to WEB's 27. noweb now supports indexing and identifier cross-reference, including hypertext ``hot links'' courtesy of Mosaic. The simple noweb manual is only 2 pages; documenting the full power of noweave and notangle requires another 3 pages. noweb works ``out of the box'' with any programming language, and its formatter-dependent part is a 60-line nawk program. The primary sacrifice relative to WEB is the loss of prettyprinting. Support: email to the author - ---------------------------------------------------------------------- - 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 - ---------------------------------------------------------------------- - ProTeX -------- Developer: Eitan Gurari Version: 1.1 (AlProTeX 1.2) Hardware: Any platform with TeX (ProTeX is written in TeX) Languages: Any language Formatter: TeX and LaTeX Availability: Anonymous ftp from: ftp.cis.ohio-state.edu : pub/tex/osu/gurari/ LPA:/independent Readme: Unknown Description: There is a book published on using ProTeX, @Book{Gurari:TLD94, author = "Eitan M. Gurari", title = "{\TeX} and {\LaTeX}: Drawing and Literate Programming", publisher = pub-MH, year = "1994", address = pub-MH:adr, bibdate = "Wed Sep 29 17:55:14 1993", acknowledgement = ack-nhfb, } Support: gurari@cis.ohio-state.edu - ---------------------------------------------------------------------- - 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 - ---------------------------------------------------------------------- - 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. - ---------------------------------------------------------------------- - 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. - ---------------------------------------------------------------------- - 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. - ---------------------------------------------------------------------- - 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. = ====================================================================== * 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. - 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. - ---------------------------------------------------------------------- - c2cweb -------- Developer: Werner Lemberg Version: 1.4 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 - ---------------------------------------------------------------------- - c2man ------- Developer: Graham Stoney Version: 2.0 patchlevel 26 Hardware: Unix, MSDOS, OS/2. Languages: C Formatter: nroff -man, texinfo (requires yacc/byacc/bison, lex/flex, and nroff/groff/texinfo/LaTeX). Availability: Anonymous ftp from ftp.wustl.edu: /usenet/comp.sources.reviewed/volume03/c2man* ftp.informatik.uni-stuttgart.de: /pub/archive/comp.sources/reviewed/c2man* Readme: See distribution. Description: The primary philosophy here is to use the programming language as far as possible to express the programmer's intentions, and to use comments only when the programming language is not sufficiently expressive. A comment can then become part of the language grammar which is recognised by a "documentation compiler". This tool parses a superset of the programming language and can automatically generate documentation in human-readable form by associating the programmer's comments with the objects in the code by their context. Support: Actively supported; mailing list available: send "subscribe c2man " (in the message body) to listserv@research.canon.oz.au. - ---------------------------------------------------------------------- - 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. - ---------------------------------------------------------------------- - 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 - ---------------------------------------------------------------------- - Funnelweb Mode ---------------- Developer: Daniel Simmons Version: Unknown Availability: Litprog archives (was in email) Anonymous ftp from: ftp.imada.ou.dk 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 - ---------------------------------------------------------------------- - 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 - ---------------------------------------------------------------------- - 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@sunbim.be - ---------------------------------------------------------------------- - TIE ----- Developer: Unknown Version: Unknown Hardware: Unknown Availability: Anonymous ftp from: LPA:/Tools Readme: Unknown Description: This software merges change files. Support: Unknown - ---------------------------------------------------------------------- - 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 = ====================================================================== * What other resources are available? ------------------------------------- - 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 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 ftp.desy.de [131.169.10.115] and get the file: /pub/userWWW/projects/Announce/LitProg.txt - ---------------------------------------------------------------------- - TeX Resources --------------- Another resource of interest to literate programmers is the info-tex mailing list. If you're using (La)TeX as your typsetting system and have access to internet, then you should investigate this mailing list. Mail list service is available through the SHSU list-server. To subscribe, send a message to LISTSERV@SHSU.EDU, and include in the message one line of text: SUBSCRIBE INFO-TEX "your name in quotes" The list is unmoderated; messages sent to info-tex@shsu.edu are automatically distributed to all subscribers and cross-posted to comp.text.tex. Archives of the mailing list and newsgroup are maintained on niord.shsu.edu [192.92.115.8] in the directory info-tex. 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. - ---------------------------------------------------------------------- - Virtual Coursework -------------------- Marcus Speh plans an introductory course on Literate Programming on the Internet, part of the first semester of "Global Network Academy" [GNA], a non-profit corporation incorporated in the state of Texas, affilated with the Usenet University project. The texts/sample programs for this class will be made available via the World-Wide Web. A special room on GNA Virtual Campus will be staffed by a consultant in one to two hour shifts. Students with questions can telnet to the virtual campus and ask questions of the staff there. If you are interested in registering for the course either as a student or as a consultant, please contact marcus@x4u.desy.de. You will receive a standard reply message; no further action will be taken until June 94. Interested parties can check the hypertext notes for the completed C++ Course done in a similar fashion, at URL http://info.desy.de:80/pub/uu-gna/html/cc/index.html [Editor's note: Because of workload, Marcus requests that email inquiries be limited to a statement of interest for either a student or consultant position until June 1994.] = ====================================================================== * 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: bart.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 written in (Levy/Knuth) CWEB. More details in the distribution. It is available via anonymous ftp from: labrea.stanford.edu:/pub/sgb = ====================================================================== * 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 several 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. = ====================================================================== * 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. = ====================================================================== * 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. = ====================================================================== * 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. = End of File ========================================================== ----- ================================================================================ Archive-Date: Fri, 03 Feb 1995 00:20:57 CDT Sender: owner-litprog@SHSU.edu From: neeri@iis.ee.ethz.ch (Matthias Neeracher) Reply-To: LitProg@SHSU.edu, neeri@IIS.EE.ETHZ.CH Subject: Re: Spidery WEB for Perl? Date: 2 Feb 1995 23:15:11 GMT Message-ID: <3grp1v$i4r@elna.ethz.ch> To: LitProg@SHSU.EDU diego@ds5000.dgsca.unam.mx (Diego Zamboni) writes: > Has somebody done something with Spidery Web for programming in >perl? Or does anybody know of some literate programming tool >apt for programming in perl? I'd recommend noweb. Perl syntax is quite complex to parse, so you'd probably spend more time fiddling with pretty-printing than programming (Of course, the fact that this argument is mostly applicable to *every* programming language is exactly what made Norman Ramsey write noweb based on his experiences with Spidery WEB - or that's the impression I got from his papers). Matthias ----- Matthias Neeracher http://err.ethz.ch/members/neeri.html "I'm set free to find a new illusion" -- Velvet Underground ================================================================================ Archive-Date: Fri, 03 Feb 1995 06:49:56 CDT Sender: owner-litprog@SHSU.edu From: maavl@cwi.nl (Marc van Leeuwen) Reply-To: LitProg@SHSU.edu, maavl@CWI.NL Subject: Re: Spidery WEB for Perl? Message-ID: Date: Fri, 3 Feb 1995 10:00:26 GMT To: LitProg@SHSU.EDU In article <3grp1v$i4r@elna.ethz.ch>, neeri@iis.ee.ethz.ch (Matthias Neeracher) writes: |> diego@ds5000.dgsca.unam.mx (Diego Zamboni) writes: |> > Has somebody done something with Spidery Web for programming in |> >perl? Or does anybody know of some literate programming tool |> >apt for programming in perl? |> |> I'd recommend noweb. Perl syntax is quite complex to parse, so you'd |> probably spend more time fiddling with pretty-printing than programming |> (Of course, the fact that this argument is mostly applicable to *every* |> programming language is exactly what made Norman Ramsey write noweb based |> on his experiences with Spidery WEB - or that's the impression I got from |> his papers). You may be right for Perl, but I disagree for the claim about every programming language. Just recently I wrote a spidery web for the GAP (computer algebra) language, which took me no more than two days, including the installation of Spidery WEB itself (that was the hardest part, it comes with the most horrid makefile I have ever had to look at), and playing around a bit with various layout styles; it works like a charm. It all depends very much on the particular language you are using. If your language has a regular and context-independent syntax, and no lexical rules that deviate from the customary ones, then Spidery WEB is fine, depite what its author might say about it. If your language is otherwise, better forget about pretty-printing (as an extreme case consider TeX; I don't think anybody even has any clear idea of what pretty-printed TeX source code would have to look like). Just as an indication, in my opinion Pascal would be fine, C is on the border, and C++ would be over the border (too much context dependence), at least, if you are serious about the full langauge and quality pretty printing. Hand written WEB systems like CWEB and FWEB can provide better results for tricky languages, but if you have to write such a system yourself, this is of course quite an investment. Nevertheless I strongly disagree with people saying that pretty-printing is not worth the effort for anyone in general; this depends very much on ones particular situation and purpose. In some cases pretty-printing may even be the main reason to opt for literate programming. Marc van Leeuwen ================================================================================ Archive-Date: Fri, 03 Feb 1995 08:30:26 CDT Sender: owner-litprog@SHSU.edu From: steve@hubcap.clemson.edu ("Steve" Stevenson) Reply-To: LitProg@SHSU.edu, steve@HUBCAP.CLEMSON.EDU Subject: Re: Pascal X(SC) Date: 3 Feb 1995 13:05:42 GMT Message-ID: <3gt9n6$ptp@hubcap.clemson.edu> To: LitProg@SHSU.EDU Folscheid Bob (FOLSCHEID_b@istvax.ist.lu) wrote: : Can anybody send me an FTP,WWW,E-Mail Adress where to find something : about Pascal XSC or Pascal SC, There is a book out by R. Hammer, et al. Numerical Toolbox for Verified Computing I. Springer-Verlag. I believe the work is done at Dortmund. -- Steve (really "D. E.") Stevenson steve@hubcap.clemson.edu Department of Computer Science, (803)656-5880.mabell Clemson University, Clemson, SC 29634-1906 Wanted: Sterbenz, P. Floating Point Computation ================================================================================ Archive-Date: Fri, 03 Feb 1995 21:24:06 CDT Sender: owner-litprog@SHSU.edu Subject: Re: Spidery WEB for Perl? Message-ID: <3gnisg$g92@bell.maths.tcd.ie> From: creilly@maths.tcd.ie (Colman Reilly) Reply-To: LitProg@SHSU.edu, creilly@MATHS.TCD.IE Date: 1 Feb 1995 09:05:20 -0000 To: LitProg@SHSU.EDU diego@ds5000.dgsca.unam.mx (Diego Zamboni) writes: >Hi: > Has somebody done something with Spidery Web for programming in >perl? Or does anybody know of some literate programming tool >apt for programming in perl? > Thanks! Please answer by email if possible, I'll summarize. I use noweb, which is language independent, and which can handle HTML being the formating language in use. Colman -- Colman Reilly (creilly@maths.tcd.ie) [+353-(0)1-7022280] c/o School of Mathematics,18.05 Westland Row,Trinity College,Dublin. PGP Public Key on Request MIME OK "Nothing so strong as gentleness; nothing so gentle as real strength." ================================================================================ Archive-Date: Fri, 03 Feb 1995 21:25:35 CDT Sender: owner-litprog@SHSU.edu From: smartin@freenet.vcu.edu Reply-To: LitProg@SHSU.edu, smartin@FREENET.VCU.EDU Subject: Qbasic..... Date: 3 Feb 1995 22:01:33 -0500 Message-ID: <3guqmd$jas@freenet.vcu.edu> To: LitProg@SHSU.EDU Hello all! I am in real need of help I have no idea if this is the plase to post beacsue every 1 seems to be talking about c or c++ but any ways I am trying to WORDS come up LETTER by LETTER sorta like when you chat with some one direct and you see what they are typing!.. well I am tring to get that to work does any 1 have any ideas ? Thanks! Scott ================================================================================ Archive-Date: Fri, 03 Feb 1995 23:40:52 CDT Sender: owner-litprog@SHSU.edu Date: Fri, 3 Feb 95 23:37:58 CST From: dhein@Onramp.NET Reply-To: LitProg@SHSU.edu, dhein@ONRAMP.NET Subject: RE: Qbasic..... To: LitProg@SHSU.edu, smartin@freenet.vcu.edu Message-ID: MIME-Version: 1.0 Content-Type: MULTIPART/MIXED; charset=US-ASCII --- Content-Type: TEXT/PLAIN; charset=US-ASCII ---------------Original Message--------------- Hello all! I am in real need of help I have no idea if this is the plase to post beacsue every 1 seems to be talking about c or c++ but any ways I am trying to WORDS come up LETTER by LETTER sorta like when you chat with some one direct and you see what they are typing!.. well I am tring to get that to work does any 1 have any ideas ? Thanks! Scott ----------End of Original Message---------- ------------------------------------- Name: Dave Hein E-mail: dhein@onramp.net Date: 02/03/95 Time: 23:37:58 ------------------------------------- --- Content-Type: TEXT/PLAIN; SizeOnDisk=58134; name="LITPROG.TXT"; CHARSET=US-ASCII Content-Description: LITPROG.TXT Path: bloom-beacon.mit.edu!senator-bedfellow.mit.edu!faqserv From: thompson@sun1.coe.ttu.edu Newsgroups: comp.programming.literate,comp.answers,news.answers Subject: comp.programming.literate FAQ Supersedes: Followup-To: comp.programming.literate Date: 16 Jan 1995 10:46:05 GMT Organization: Texas Tech University, Lubbock, Texas, USA Lines: 1543 Approved: news-answers-request@MIT.Edu Distribution: world Expires: 14 Feb 1995 10:45:13 GMT Message-ID: Reply-To: thompson@sun1.coe.ttu.edu NNTP-Posting-Host: bloom-picayune.mit.edu Summary: Literate Programming FAQ--general introduction to the concepts of literate programming and the tools available to write literate programs. X-Last-Updated: 1994/08/23 Originator: faqserv@bloom-picayune.MIT.EDU Xref: bloom-beacon.mit.edu comp.programming.literate:1836 comp.answers:9537 news.answers:33215 Archive-name: literate-programming-faq Last-modified: 1994/08/23 Version: 1.1.10 Welcome to the Literate Programming Frequently Asked Questions List ------------------------------------------------------------------- This version was created Tuesday, August 23, 1994, and should considered stale after 90 days. Information contained in this document is the best available at preparation. The original file was dated October 15, 1993 (just for historical purposes). 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." Copyright 1993, 1994 David B. Thompson. All rights reserved worldwide. Permission is granted to copy this document for free distribution so long as it remains intact and unmodified. For other arrangements, contact the author/maintainer via email: thompson@sun1.coe.ttu.edu. What's New? ----------- + Add Fold2Web entry. + Correct noweb.el entry. (Thanks Dominique!) + Update nuweb.el entry. + Update SchemeWEB entry. + Update WWW and literate programming entry. + Update c2cweb entry. = ====================================================================== * 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, who can be reached at: thompson@sun1.coe.ttu.edu * Preferred mailing address for FAQ related comments/questions. wqdbt@ttacs1.ttu.edu * Forwarded to my pc. Comment and constructive criticism is 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 not be complete for some months. Nevertheless, the information contained herein may be useful to some. Use it as it is intended. - ---------------------------------------------------------------------- - Typography ------------ Major sections of the FAQ are divided by double lines (====). Minor sections and other divisions are separated by single lines (----). Major topics use a "* " as a leader. Minor topics use a "- " as a leader. This should simplify searching for topics. = ====================================================================== Table of Contents: ------------------ * Introduction, or "What's this all about?" - Typography * How do I get the FAQ? - Literate Programming FAQ - FWEB FAQ * Is there a newsgroup? (The comp.programming.literate newsgroup) * What internet nodes are of interest to literate programmers? * What is literate programming? * How do I begin literate programming? * What literate programming tools are available and where are they? - APLWEB - AWEB - CLiP - CWEB - FunnelWeb - FWEB - IMPACT - lit2x - Literate Programmer's Workshop (LPW) - MapleWEB - MWEB (Schrod/Detig) - MWEB (Sewell) - noweb - nuweb - ProTeX - RWEB - SchemeWEB - Spidery WEB - WEB - WinWordWEB * Are there other tools I should know about? - C2LaTeX - c2cweb - c2man - cnoweb - Fold2web - FunnelWeb mode - noweb.el - nuweb.el - TIE - Web mode * What other resources are available? - World Wide Web - TeX Resources - Virtual Coursework * Are there any code examples? - Examples included with developer's tools - Cameron Smith's KR-CWEB - Stanford GraphBase * Bibliographies. * How to anonymously ftp. * Acknowledgements. * End notes. = ====================================================================== * How do I get the FAQ? ----------------------- - 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.") An alternative is to use the fileserver at Sam Houston State University (SHSU). Send a message to FILESERV@SHSU.EDU and include in your message: SENDME LITPROG.FAQ The file server will forward a copy of the file to you via email. - ---------------------------------------------------------------------- - FWEB FAQ ---------- Marcus Speh maintains the FWEB FAQ. The current version number is 1.29. It can be retrieved in the same way as this FAQ; either by anonymous ftp or through the SHSU file server. On the SHSU server, the file name is FAQ.FWEB. Invoke your ftp software, open a connection to NIORD.SHSU.EDU [192.92.115.8], attach to the directory FAQ, and transfer the file FAQ.FWEB. Alternatively, send a message to the file server, FILESERV@SHSU.EDU, and include the following text in a one line message: SENDME FAQ.FWEB The file server will send the current version of the file via email. 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 (LPA) in the directory LPA/Documentation/faq/fweb (see the references to LPA below for more information). Also, Marcus Speh is looking for someone willing to take over the FWEB FAQ. The text of his email message follows... "Please add to the FWEB FAQ the note that I am looking for someone to take the maintenance of the FAQ over - I am ready to assist in any way whatsoever, including tons of mail, notes for v1.29->v1.30, Texinfo sources, a WWW server and Hypertextification etc." If you're interested, send mail to marcus@x4u2.desy.de and express your willingness to serve. = ====================================================================== * Is there a newsgroup? ----------------------- One of the most important resources is the literate programming newsgroup, comp.programming.literate. You can read this newsgroup using your standard reader. Altenatively, the newsgroup is gated to a mailing list hosted by George Greenwade and Sam Houston State University. You can subscribe by sending mail to the list-server, LISTSERV@SHSU.EDU, and include in the message one line of text: SUBSCRIBE LITPROG "your name in quotes" The list is unmoderated; messages sent to litprog@shsu.edu are automatically distributed to all subscribers and cross-posted to comp.programming.literate. Archives of the mailing list and newsgroup are maintained on niord.shsu.edu [192.92.115.8] in the directory litprog. = ====================================================================== * 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. The CTAN sites are: ftp host IP CTAN root Institution and Sponsor ------------------------------------------------------------------------- ftp.tex.ac.uk 134.151.79.32 pub/archive Aston Univ./UK TeX U.G. ftp.dante.de 129.206.100.192 soft/tex DANTE e.V. ftp.shsu.edu 192.92.115.10 tex-archive Sam Houston State Univ. Other nodes and directories of interest include: Node: niord.shsu.edu [192.92.115.8] Directory: various (do some snooping!) Notes: Has a gopher server. 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/ = ====================================================================== * 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 programmer, who wants to provide the best possible documentation 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 document such a program we want to explain each individual part of the web and how it relates to its neighbours. The typographic 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 combining the two, we can develop a style of programming that maximizes our ability to perceive the structure of a complex piece of software, and at the same time the documented programs 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 = ====================================================================== * 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. = ====================================================================== * What literate programming tools are available and where are they? ------------------------------------------------------------------- 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. :-) - ---------------------------------------------------------------------- - 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. - ---------------------------------------------------------------------- - 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. - ---------------------------------------------------------------------- - CLiP ------ Developer: E.W. van Ammers and M.R. Kramer Version: Unknown Hardware: Vax/VMS, Unix, and MS-DOS Languages: Any programming language. Formatter: Any formatter (TeX, LaTeX, Troff, Runoff, etc) or any wordprocessor including WYSIWYG systems (Word Perfect, Win Word, Ami Pro, Word, etc.) Availability: Anonymous ftp from: sun01.info.wau.nl:/CLIP/ms_dos MS-DOS version sun01.info.wau.nl:/CLIP/vax_vms VAX/VMS version CTAN:/web/clip LPA:/machines/ms-dos LPA:/machines/vax Readme: With bundle above Description: CLiP does not use explicite commands to perform the extraction process. Rather it recognizes pseudostatemens written as comments in the programming language in question. CLiP distinguishes pseudostatments from ordinary comments because the former comply with a 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 but we have not yet experimented with this form of documentation. 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 documentatio 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 segements. + 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: ammers@rcl.wau.nl - ---------------------------------------------------------------------- - 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 Note: A fork of CWEB 3.x was developed by Marc van Leeuwen which implements several changes to CWEB. It is available for anonymous ftp from ftp.cwi.nl:pub/cweb. The principle changes are: - Scans include files for typedef definitions - Grammar and formatting rules are well separated, allowing for run-time selection of a rule set (via command line option) - New manual. - ---------------------------------------------------------------------- - 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. - ---------------------------------------------------------------------- - FWEB ------ Developer: John A. Krommes Version: 1.30a (1.40 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: Plain TeX and LaTeX. 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 - ---------------------------------------------------------------------- - 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. - ---------------------------------------------------------------------- - lit2x ------- Developer: Unknown Version: Unknown Hardware: Unknown Languages: Unknown Formatter: Unknown Availability: Anonymous ftp from: LPA:/independent Readme: Unknown Description: None available Support: Unknown - ---------------------------------------------------------------------- - 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. - ---------------------------------------------------------------------- - MapleWEB ---------- Developer: Unknown Version: Unknown Hardware: Unknown Languages: Maple Formatter: Unknown Availability: Anonymous ftp from: LPA:/maple Readme: Unknown Description: None Support: Unknown - ---------------------------------------------------------------------- - 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. - ---------------------------------------------------------------------- - 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. - ---------------------------------------------------------------------- - noweb ------- Developer: Norman Ramsey Version: 2.6 Hardware: Unix and DOS platforms. Languages: All programming languages. Formatter: Plain TeX, LaTeX, and HTML (Mosaic) formatters. Availability: Anonymous ftp from: CTAN:/web/noweb LPA:/independent DOS version also in LPA:/machines/ms-dos also bart.kean.edu:/pub/leew Last recourse, use bellcore.com:/pub/norman Readme: With bundle above. Description: noweb is designed to meet the needs of literate programmers while remaining as simple as possible. Its primary advantages are simplicity, extensibility, and language-independence. noweb uses 5 control sequences to WEB's 27. noweb now supports indexing and identifier cross-reference, including hypertext ``hot links'' courtesy of Mosaic. The simple noweb manual is only 2 pages; documenting the full power of noweave and notangle requires another 3 pages. noweb works ``out of the box'' with any programming language, and its formatter-dependent part is a 60-line nawk program. The primary sacrifice relative to WEB is the loss of prettyprinting. Support: email to the author - ---------------------------------------------------------------------- - 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 - ---------------------------------------------------------------------- - ProTeX -------- Developer: Eitan Gurari Version: 1.1 (AlProTeX 1.2) Hardware: Any platform with TeX (ProTeX is written in TeX) Languages: Any language Formatter: TeX and LaTeX Availability: Anonymous ftp from: ftp.cis.ohio-state.edu : pub/tex/osu/gurari/ LPA:/independent Readme: Unknown Description: There is a book published on using ProTeX, @Book{Gurari:TLD94, author = "Eitan M. Gurari", title = "{\TeX} and {\LaTeX}: Drawing and Literate Programming", publisher = pub-MH, year = "1994", address = pub-MH:adr, bibdate = "Wed Sep 29 17:55:14 1993", acknowledgement = ack-nhfb, } Support: gurari@cis.ohio-state.edu - ---------------------------------------------------------------------- - 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 - ---------------------------------------------------------------------- - 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. - ---------------------------------------------------------------------- - 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. - ---------------------------------------------------------------------- - 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. - ---------------------------------------------------------------------- - 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. = ====================================================================== * 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. - 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. - ---------------------------------------------------------------------- - c2cweb -------- Developer: Werner Lemberg Version: 1.4 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 - ---------------------------------------------------------------------- - c2man ------- Developer: Graham Stoney Version: 2.0 patchlevel 26 Hardware: Unix, MSDOS, OS/2. Languages: C Formatter: nroff -man, texinfo (requires yacc/byacc/bison, lex/flex, and nroff/groff/texinfo/LaTeX). Availability: Anonymous ftp from ftp.wustl.edu: /usenet/comp.sources.reviewed/volume03/c2man* ftp.informatik.uni-stuttgart.de: /pub/archive/comp.sources/reviewed/c2man* Readme: See distribution. Description: The primary philosophy here is to use the programming language as far as possible to express the programmer's intentions, and to use comments only when the programming language is not sufficiently expressive. A comment can then become part of the language grammar which is recognised by a "documentation compiler". This tool parses a superset of the programming language and can automatically generate documentation in human-readable form by associating the programmer's comments with the objects in the code by their context. Support: Actively supported; mailing list available: send "subscribe c2man " (in the message body) to listserv@research.canon.oz.au. - ---------------------------------------------------------------------- - 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. - ---------------------------------------------------------------------- - 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 - ---------------------------------------------------------------------- - Funnelweb Mode ---------------- Developer: Daniel Simmons Version: Unknown Availability: Litprog archives (was in email) Anonymous ftp from: ftp.imada.ou.dk 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 - ---------------------------------------------------------------------- - 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 - ---------------------------------------------------------------------- - 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@sunbim.be - ---------------------------------------------------------------------- - TIE ----- Developer: Unknown Version: Unknown Hardware: Unknown Availability: Anonymous ftp from: LPA:/Tools Readme: Unknown Description: This software merges change files. Support: Unknown - ---------------------------------------------------------------------- - 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 = ====================================================================== * What other resources are available? ------------------------------------- - 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 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 ftp.desy.de [131.169.10.115] and get the file: /pub/userWWW/projects/Announce/LitProg.txt - ---------------------------------------------------------------------- - TeX Resources --------------- Another resource of interest to literate programmers is the info-tex mailing list. If you're using (La)TeX as your typsetting system and have access to internet, then you should investigate this mailing list. Mail list service is available through the SHSU list-server. To subscribe, send a message to LISTSERV@SHSU.EDU, and include in the message one line of text: SUBSCRIBE INFO-TEX "your name in quotes" The list is unmoderated; messages sent to info-tex@shsu.edu are automatically distributed to all subscribers and cross-posted to comp.text.tex. Archives of the mailing list and newsgroup are maintained on niord.shsu.edu [192.92.115.8] in the directory info-tex. 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. - ---------------------------------------------------------------------- - Virtual Coursework -------------------- Marcus Speh plans an introductory course on Literate Programming on the Internet, part of the first semester of "Global Network Academy" [GNA], a non-profit corporation incorporated in the state of Texas, affilated with the Usenet University project. The texts/sample programs for this class will be made available via the World-Wide Web. A special room on GNA Virtual Campus will be staffed by a consultant in one to two hour shifts. Students with questions can telnet to the virtual campus and ask questions of the staff there. If you are interested in registering for the course either as a student or as a consultant, please contact marcus@x4u.desy.de. You will receive a standard reply message; no further action will be taken until June 94. Interested parties can check the hypertext notes for the completed C++ Course done in a similar fashion, at URL http://info.desy.de:80/pub/uu-gna/html/cc/index.html [Editor's note: Because of workload, Marcus requests that email inquiries be limited to a statement of interest for either a student or consultant position until June 1994.] = ====================================================================== * 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: bart.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 written in (Levy/Knuth) CWEB. More details in the distribution. It is available via anonymous ftp from: labrea.stanford.edu:/pub/sgb = ====================================================================== * 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 several 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. = ====================================================================== * 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. = ====================================================================== * 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. = ====================================================================== * 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. = End of File ========================================================== ----- ================================================================================ Archive-Date: Sat, 04 Feb 1995 09:24:56 CDT Sender: owner-litprog@SHSU.edu From: wmschalck@aol.com (WMSchalck) Subject: I'm from AOL - Don't flame me yet... Date: 4 Feb 1995 09:55:39 -0500 Message-ID: <3h04hb$2l4@newsbf02.news.aol.com> Reply-To: LitProg@SHSU.edu, wmschalck@aol.com (WMSchalck) To: LitProg@SHSU.EDU I posted a message for AOL a few days ago to see if they would update the description of this newsgroup. No change yet and no response from AOL (big suprise) ================================================================================ Archive-Date: Sat, 04 Feb 1995 11:04:08 CDT Sender: owner-litprog@SHSU.edu From: larstr@edb.tih.no (Lars Troen) Reply-To: LitProg@SHSU.edu, larstr@EDB.TIH.NO Subject: Re: borland or visual c++ ? Date: 4 Feb 1995 13:26:32 GMT Message-ID: <3gvva8$m8h@astfgl.edb.tih.no> To: LitProg@SHSU.EDU Gil Kedem (gk@vangogh.med.jhu.edu) wrote: : I am about to write c++ software for pc's and I do not know which : compiler to use. The program will have nice Windows interfacing, and will : involve signal acquisition and some digital signal processing. : Does anyone know which is better? Visual C++ or Borland C++? : (or maybe something else) I don't know much about signal processing, but the best compiler for Windows is Visual C++. -- (***************************************************************************) (* Lars Trøen på Høgskolen i Sør-Trøndelag *) (* "The key, the whole key, and nothing but the key. So help me Codd." *) (* Who is General Failure and why is he reading my C: drive? *) (***************************************************************************) ================================================================================ Archive-Date: Sat, 04 Feb 1995 11:15:35 CDT Sender: owner-litprog@SHSU.edu From: wesleymc@aol.com (WesleyMc) Subject: Re: C++ for 486 PC Date: 4 Feb 1995 11:57:59 -0500 Message-ID: <3h0bmn$3rd@newsbf02.news.aol.com> Reply-To: LitProg@SHSU.edu, wesleymc@aol.com (WesleyMc) To: LitProg@SHSU.EDU Borland makes Turbo C/C++ for DOS, Turbo C/C++ for Windows, and a version for DOS and Windows. When I purchased the Windows version I was new at C++, now I own both version, and have found it very easy to use. I paid about $75 for each. ================================================================================ Archive-Date: Sat, 04 Feb 1995 11:18:41 CDT Sender: owner-litprog@SHSU.edu Date: Sat, 4 Feb 95 08:07:09 CST From: dhein@Onramp.NET Reply-To: LitProg@SHSU.edu, dhein@ONRAMP.NET Subject: TEST -- ignore this note To: LIST LitProg Message-ID: MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII Just a test. ------------------------------------- Name: Dave Hein E-mail: dhein@onramp.net Date: 02/04/95 Time: 08:07:09 ------------------------------------- ================================================================================ Archive-Date: Sat, 04 Feb 1995 12:02:32 CDT Sender: owner-litprog@SHSU.edu Message-ID: Date: Sat, 4 Feb 95 12:05 CST MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" To: LitProg@SHSU.edu From: hti@sccsi.com (Chris Skolaut) Reply-To: LitProg@SHSU.edu, hti@SCCSI.COM Subject: unsubscribe ================================================================================ Archive-Date: Sat, 04 Feb 1995 16:47:24 CDT Sender: owner-litprog@SHSU.edu From: ptjm@io.org (Patrick TJ McPhee) Reply-To: LitProg@SHSU.edu, ptjm@IO.ORG Subject: Re: Clueless questions about literate programming are welcome here Date: 4 Feb 1995 12:59:05 -0500 Message-ID: <3h0f99$6dl@ionews.io.org> To: LitProg@SHSU.EDU In article , Ryan Davis wrote: % 1) Is there a FAQ? There is. The last one I have was dated May 27, so perhaps it's no longer maintained (or perhaps I just haven't saved it for a while). Try rtfm.mit.edu. % 2) Is Literate programming just a means of pretty printing and automating % documentation? No. At least in my view, literate programming is a mechanism for writing programs which are relatively easy to maintain. Apart from encouraging verbose comments, literate programming places emphasis on explaining how and why a program was written the way it was, and it provdes a mechanism for laying the program out in a way which will best aid understanding. A potential side-benefit of this is that the literate programmer has to think twice about everything, which can help uncover problems before they get into production systems and lead to the end of civilisation. % 3) Is there any implementations of *WEB* that are macintosh compatible, OR % that are machine independant and will run with PERL or some other widely % available language? There's an MPW litprog tool, which I suppose is in the archive at Darmstadt. I don't really know what languages or formatters it supports, and the Mac programmers where I work were not in any way interested in it :(. % 4) I've noticed several *WEB* thingies are C, C++, Pascal...... % literate(?) but never have I seen the word smalltalk... anyone? There are a few packages that don't worry about the source code. FunnelWeb, noweb and nuweb come to mind. Take care. -- Patrick TJ McPhee Toronto Canada ptjm@io.org ================================================================================ Archive-Date: Sat, 04 Feb 1995 20:43:23 CDT Sender: owner-litprog@SHSU.edu From: nkirsch@omnifest.uwm.edu (Nick F. Kirsch) Reply-To: LitProg@SHSU.edu, nkirsch@OMNIFEST.UWM.EDU Subject: Cdrom Package Date: 4 Feb 1995 20:37:43 -0600 Message-ID: <3h1dln$vu6@omnifest.uwm.edu> To: LitProg@SHSU.EDU There's a new cdrom package/book out that tells you how to create games like doom. If anyone has heard about it can you please post some info about it here. =|:-)= ) \ / ( /|\ )\_/( /|\ * / | \ (/\|/\) / | \ * |`.________________ /__|__O____\`|'/____O__|__\________________.'| | Nicholas J. Kirsch '^` \|/ '^` | | V | | nkirsch@omnifest.uwm.edu "By keeping your mouth | | -=<*OR*>=- closed you may seem dumb, | | nkirsch@aol.com But by opening your mouth | | you may prove it." | | --Pres. Lincoln | | .__________________________________________________________. | | ' | | | (( | | | ` | |' | /\ / \\ \ /\ | `| * | / V )) V \ | * |/ // \| V ================================================================================ Archive-Date: Sat, 04 Feb 1995 21:15:08 CDT Sender: owner-litprog@SHSU.edu From: wmschalck@aol.com (WMSchalck) Subject: Re: Qbasic..... Date: 4 Feb 1995 22:01:07 -0500 Message-ID: <3h1f1j$ats@newsbf02.news.aol.com> Reply-To: LitProg@SHSU.edu, wmschalck@aol.com (WMSchalck) To: LitProg@SHSU.EDU > Hello all! I am in real need of help I have no idea if this > is the plase to post beacsue every 1 seems to be talking about > c or c++ but any ways I am trying to WORDS come up LETTER by > LETTER sorta like when you chat with some one direct and you > see what they are typing!.. well I am tring to get that to work > does any 1 have any ideas ? > Thanks! > Scott HUH? ================================================================================ Archive-Date: Sun, 05 Feb 1995 11:06:20 CDT Sender: owner-litprog@SHSU.edu From: ah277@lafn.org (Ryan Retting) Subject: Procomm ASPECT info Message-ID: <1995Feb4.224650.1915@lafn.org> Reply-To: LitProg@SHSU.edu, ah277@lafn.org (Ryan Retting) Date: Sat, 4 Feb 1995 22:46:50 GMT To: LitProg@SHSU.EDU Does anybody know of a newsgroup or knows the Procomm Plus for Windows ASPECT script language? E-Mail would be appreciated (ah277@lafn.org) -Ryan -- _____ __ __ ______ __ __ .. Ryan Retting _ ah277@lafn.org .. / __ / / /_/ / / __ / / \/ / .. o ___ _| |__ ... / __/ \__ / / /_/ / / / / / .. <-\ |___| /_ _/ .... /_/\\ /_/ /_/ / / /_/\__/ .. // \_ - \_/ LA KINGS ..... ================================================================================ Archive-Date: Sun, 05 Feb 1995 19:45:06 CDT Sender: owner-litprog@SHSU.edu From: wmschalck@aol.com (WMSchalck) Subject: Re: Cdrom Package Date: 5 Feb 1995 19:24:35 -0500 Message-ID: <3h3q83$2af@newsbf02.news.aol.com> Reply-To: LitProg@SHSU.edu, wmschalck@aol.com (WMSchalck) To: LitProg@SHSU.EDU > There's a new cdrom package/book out that tells you how to create games like > doom. If anyone has heard about it can you please post some info about it > here. =|:-)= > > | nkirsch@omnifest.uwm.edu "By keeping your mouth | > | -=<*OR*>=- closed you may seem dumb, | > | nkirsch@aol.com But by opening your mouth | > | you may prove it." | > | --Pres. Lincoln | Nicholas opened his mouth and proved it! ;-) wmschalck@aol.com fhwc93a@prodigy.com 74247,1336@compuserve.com ================================================================================ Archive-Date: Mon, 06 Feb 1995 06:20:29 CDT Sender: owner-litprog@SHSU.edu Date: Mon, 6 Feb 95 06:18:20 CST From: dhein@Onramp.NET Reply-To: LitProg@SHSU.edu, dhein@ONRAMP.NET Subject: RE: Cdrom Package To: LitProg@SHSU.edu, nkirsch@omnifest.uwm.edu Message-ID: MIME-Version: 1.0 Content-Type: MULTIPART/MIXED; charset=US-ASCII --- Content-Type: TEXT/PLAIN; charset=US-ASCII Post to some other news group. Comp.Programming.Literate FAQ is attached. Look at the rec.games.* hierarchy. ---------------Original Message--------------- There's a new cdrom package/book out that tells you how to create games like doom. If anyone has heard about it can you please post some info about it here. =|:-)= ) \ / ( /|\ )\_/( /|\ * / | \ (/\|/\) / | \ * |`.________________ /__|__O____\`|'/____O__|__\________________.'| | Nicholas J. Kirsch '^` \|/ '^` | | V | | nkirsch@omnifest.uwm.edu "By keeping your mouth | | -=<*OR*>=- closed you may seem dumb, | | nkirsch@aol.com But by opening your mouth | | you may prove it." | | --Pres. Lincoln | | .__________________________________________________________. | | ' | | | (( | | | ` | |' | /\ / \\ \ /\ | `| * | / V )) V \ | * |/ // \| V ----------End of Original Message---------- ------------------------------------- Name: Dave Hein E-mail: dhein@onramp.net Date: 02/06/95 Time: 06:18:20 ------------------------------------- --- Content-Type: TEXT/PLAIN; SizeOnDisk=58134; name="LITPROG.TXT"; CHARSET=US-ASCII Content-Description: LITPROG.TXT Path: bloom-beacon.mit.edu!senator-bedfellow.mit.edu!faqserv From: thompson@sun1.coe.ttu.edu Newsgroups: comp.programming.literate,comp.answers,news.answers Subject: comp.programming.literate FAQ Supersedes: Followup-To: comp.programming.literate Date: 16 Jan 1995 10:46:05 GMT Organization: Texas Tech University, Lubbock, Texas, USA Lines: 1543 Approved: news-answers-request@MIT.Edu Distribution: world Expires: 14 Feb 1995 10:45:13 GMT Message-ID: Reply-To: thompson@sun1.coe.ttu.edu NNTP-Posting-Host: bloom-picayune.mit.edu Summary: Literate Programming FAQ--general introduction to the concepts of literate programming and the tools available to write literate programs. X-Last-Updated: 1994/08/23 Originator: faqserv@bloom-picayune.MIT.EDU Xref: bloom-beacon.mit.edu comp.programming.literate:1836 comp.answers:9537 news.answers:33215 Archive-name: literate-programming-faq Last-modified: 1994/08/23 Version: 1.1.10 Welcome to the Literate Programming Frequently Asked Questions List ------------------------------------------------------------------- This version was created Tuesday, August 23, 1994, and should considered stale after 90 days. Information contained in this document is the best available at preparation. The original file was dated October 15, 1993 (just for historical purposes). 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." Copyright 1993, 1994 David B. Thompson. All rights reserved worldwide. Permission is granted to copy this document for free distribution so long as it remains intact and unmodified. For other arrangements, contact the author/maintainer via email: thompson@sun1.coe.ttu.edu. What's New? ----------- + Add Fold2Web entry. + Correct noweb.el entry. (Thanks Dominique!) + Update nuweb.el entry. + Update SchemeWEB entry. + Update WWW and literate programming entry. + Update c2cweb entry. = ====================================================================== * 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, who can be reached at: thompson@sun1.coe.ttu.edu * Preferred mailing address for FAQ related comments/questions. wqdbt@ttacs1.ttu.edu * Forwarded to my pc. Comment and constructive criticism is 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 not be complete for some months. Nevertheless, the information contained herein may be useful to some. Use it as it is intended. - ---------------------------------------------------------------------- - Typography ------------ Major sections of the FAQ are divided by double lines (====). Minor sections and other divisions are separated by single lines (----). Major topics use a "* " as a leader. Minor topics use a "- " as a leader. This should simplify searching for topics. = ====================================================================== Table of Contents: ------------------ * Introduction, or "What's this all about?" - Typography * How do I get the FAQ? - Literate Programming FAQ - FWEB FAQ * Is there a newsgroup? (The comp.programming.literate newsgroup) * What internet nodes are of interest to literate programmers? * What is literate programming? * How do I begin literate programming? * What literate programming tools are available and where are they? - APLWEB - AWEB - CLiP - CWEB - FunnelWeb - FWEB - IMPACT - lit2x - Literate Programmer's Workshop (LPW) - MapleWEB - MWEB (Schrod/Detig) - MWEB (Sewell) - noweb - nuweb - ProTeX - RWEB - SchemeWEB - Spidery WEB - WEB - WinWordWEB * Are there other tools I should know about? - C2LaTeX - c2cweb - c2man - cnoweb - Fold2web - FunnelWeb mode - noweb.el - nuweb.el - TIE - Web mode * What other resources are available? - World Wide Web - TeX Resources - Virtual Coursework * Are there any code examples? - Examples included with developer's tools - Cameron Smith's KR-CWEB - Stanford GraphBase * Bibliographies. * How to anonymously ftp. * Acknowledgements. * End notes. = ====================================================================== * How do I get the FAQ? ----------------------- - 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.") An alternative is to use the fileserver at Sam Houston State University (SHSU). Send a message to FILESERV@SHSU.EDU and include in your message: SENDME LITPROG.FAQ The file server will forward a copy of the file to you via email. - ---------------------------------------------------------------------- - FWEB FAQ ---------- Marcus Speh maintains the FWEB FAQ. The current version number is 1.29. It can be retrieved in the same way as this FAQ; either by anonymous ftp or through the SHSU file server. On the SHSU server, the file name is FAQ.FWEB. Invoke your ftp software, open a connection to NIORD.SHSU.EDU [192.92.115.8], attach to the directory FAQ, and transfer the file FAQ.FWEB. Alternatively, send a message to the file server, FILESERV@SHSU.EDU, and include the following text in a one line message: SENDME FAQ.FWEB The file server will send the current version of the file via email. 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 (LPA) in the directory LPA/Documentation/faq/fweb (see the references to LPA below for more information). Also, Marcus Speh is looking for someone willing to take over the FWEB FAQ. The text of his email message follows... "Please add to the FWEB FAQ the note that I am looking for someone to take the maintenance of the FAQ over - I am ready to assist in any way whatsoever, including tons of mail, notes for v1.29->v1.30, Texinfo sources, a WWW server and Hypertextification etc." If you're interested, send mail to marcus@x4u2.desy.de and express your willingness to serve. = ====================================================================== * Is there a newsgroup? ----------------------- One of the most important resources is the literate programming newsgroup, comp.programming.literate. You can read this newsgroup using your standard reader. Altenatively, the newsgroup is gated to a mailing list hosted by George Greenwade and Sam Houston State University. You can subscribe by sending mail to the list-server, LISTSERV@SHSU.EDU, and include in the message one line of text: SUBSCRIBE LITPROG "your name in quotes" The list is unmoderated; messages sent to litprog@shsu.edu are automatically distributed to all subscribers and cross-posted to comp.programming.literate. Archives of the mailing list and newsgroup are maintained on niord.shsu.edu [192.92.115.8] in the directory litprog. = ====================================================================== * 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. The CTAN sites are: ftp host IP CTAN root Institution and Sponsor ------------------------------------------------------------------------- ftp.tex.ac.uk 134.151.79.32 pub/archive Aston Univ./UK TeX U.G. ftp.dante.de 129.206.100.192 soft/tex DANTE e.V. ftp.shsu.edu 192.92.115.10 tex-archive Sam Houston State Univ. Other nodes and directories of interest include: Node: niord.shsu.edu [192.92.115.8] Directory: various (do some snooping!) Notes: Has a gopher server. 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/ = ====================================================================== * 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 programmer, who wants to provide the best possible documentation 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 document such a program we want to explain each individual part of the web and how it relates to its neighbours. The typographic 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 combining the two, we can develop a style of programming that maximizes our ability to perceive the structure of a complex piece of software, and at the same time the documented programs 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 = ====================================================================== * 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. = ====================================================================== * What literate programming tools are available and where are they? ------------------------------------------------------------------- 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. :-) - ---------------------------------------------------------------------- - 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. - ---------------------------------------------------------------------- - 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. - ---------------------------------------------------------------------- - CLiP ------ Developer: E.W. van Ammers and M.R. Kramer Version: Unknown Hardware: Vax/VMS, Unix, and MS-DOS Languages: Any programming language. Formatter: Any formatter (TeX, LaTeX, Troff, Runoff, etc) or any wordprocessor including WYSIWYG systems (Word Perfect, Win Word, Ami Pro, Word, etc.) Availability: Anonymous ftp from: sun01.info.wau.nl:/CLIP/ms_dos MS-DOS version sun01.info.wau.nl:/CLIP/vax_vms VAX/VMS version CTAN:/web/clip LPA:/machines/ms-dos LPA:/machines/vax Readme: With bundle above Description: CLiP does not use explicite commands to perform the extraction process. Rather it recognizes pseudostatemens written as comments in the programming language in question. CLiP distinguishes pseudostatments from ordinary comments because the former comply with a 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 but we have not yet experimented with this form of documentation. 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 documentatio 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 segements. + 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: ammers@rcl.wau.nl - ---------------------------------------------------------------------- - 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 Note: A fork of CWEB 3.x was developed by Marc van Leeuwen which implements several changes to CWEB. It is available for anonymous ftp from ftp.cwi.nl:pub/cweb. The principle changes are: - Scans include files for typedef definitions - Grammar and formatting rules are well separated, allowing for run-time selection of a rule set (via command line option) - New manual. - ---------------------------------------------------------------------- - 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. - ---------------------------------------------------------------------- - FWEB ------ Developer: John A. Krommes Version: 1.30a (1.40 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: Plain TeX and LaTeX. 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 - ---------------------------------------------------------------------- - 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. - ---------------------------------------------------------------------- - lit2x ------- Developer: Unknown Version: Unknown Hardware: Unknown Languages: Unknown Formatter: Unknown Availability: Anonymous ftp from: LPA:/independent Readme: Unknown Description: None available Support: Unknown - ---------------------------------------------------------------------- - 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. - ---------------------------------------------------------------------- - MapleWEB ---------- Developer: Unknown Version: Unknown Hardware: Unknown Languages: Maple Formatter: Unknown Availability: Anonymous ftp from: LPA:/maple Readme: Unknown Description: None Support: Unknown - ---------------------------------------------------------------------- - 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. - ---------------------------------------------------------------------- - 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. - ---------------------------------------------------------------------- - noweb ------- Developer: Norman Ramsey Version: 2.6 Hardware: Unix and DOS platforms. Languages: All programming languages. Formatter: Plain TeX, LaTeX, and HTML (Mosaic) formatters. Availability: Anonymous ftp from: CTAN:/web/noweb LPA:/independent DOS version also in LPA:/machines/ms-dos also bart.kean.edu:/pub/leew Last recourse, use bellcore.com:/pub/norman Readme: With bundle above. Description: noweb is designed to meet the needs of literate programmers while remaining as simple as possible. Its primary advantages are simplicity, extensibility, and language-independence. noweb uses 5 control sequences to WEB's 27. noweb now supports indexing and identifier cross-reference, including hypertext ``hot links'' courtesy of Mosaic. The simple noweb manual is only 2 pages; documenting the full power of noweave and notangle requires another 3 pages. noweb works ``out of the box'' with any programming language, and its formatter-dependent part is a 60-line nawk program. The primary sacrifice relative to WEB is the loss of prettyprinting. Support: email to the author - ---------------------------------------------------------------------- - 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 - ---------------------------------------------------------------------- - ProTeX -------- Developer: Eitan Gurari Version: 1.1 (AlProTeX 1.2) Hardware: Any platform with TeX (ProTeX is written in TeX) Languages: Any language Formatter: TeX and LaTeX Availability: Anonymous ftp from: ftp.cis.ohio-state.edu : pub/tex/osu/gurari/ LPA:/independent Readme: Unknown Description: There is a book published on using ProTeX, @Book{Gurari:TLD94, author = "Eitan M. Gurari", title = "{\TeX} and {\LaTeX}: Drawing and Literate Programming", publisher = pub-MH, year = "1994", address = pub-MH:adr, bibdate = "Wed Sep 29 17:55:14 1993", acknowledgement = ack-nhfb, } Support: gurari@cis.ohio-state.edu - ---------------------------------------------------------------------- - 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 - ---------------------------------------------------------------------- - 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. - ---------------------------------------------------------------------- - 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. - ---------------------------------------------------------------------- - 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. - ---------------------------------------------------------------------- - 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. = ====================================================================== * 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. - 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. - ---------------------------------------------------------------------- - c2cweb -------- Developer: Werner Lemberg Version: 1.4 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 - ---------------------------------------------------------------------- - c2man ------- Developer: Graham Stoney Version: 2.0 patchlevel 26 Hardware: Unix, MSDOS, OS/2. Languages: C Formatter: nroff -man, texinfo (requires yacc/byacc/bison, lex/flex, and nroff/groff/texinfo/LaTeX). Availability: Anonymous ftp from ftp.wustl.edu: /usenet/comp.sources.reviewed/volume03/c2man* ftp.informatik.uni-stuttgart.de: /pub/archive/comp.sources/reviewed/c2man* Readme: See distribution. Description: The primary philosophy here is to use the programming language as far as possible to express the programmer's intentions, and to use comments only when the programming language is not sufficiently expressive. A comment can then become part of the language grammar which is recognised by a "documentation compiler". This tool parses a superset of the programming language and can automatically generate documentation in human-readable form by associating the programmer's comments with the objects in the code by their context. Support: Actively supported; mailing list available: send "subscribe c2man " (in the message body) to listserv@research.canon.oz.au. - ---------------------------------------------------------------------- - 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. - ---------------------------------------------------------------------- - 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 - ---------------------------------------------------------------------- - Funnelweb Mode ---------------- Developer: Daniel Simmons Version: Unknown Availability: Litprog archives (was in email) Anonymous ftp from: ftp.imada.ou.dk 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 - ---------------------------------------------------------------------- - 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 - ---------------------------------------------------------------------- - 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@sunbim.be - ---------------------------------------------------------------------- - TIE ----- Developer: Unknown Version: Unknown Hardware: Unknown Availability: Anonymous ftp from: LPA:/Tools Readme: Unknown Description: This software merges change files. Support: Unknown - ---------------------------------------------------------------------- - 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 = ====================================================================== * What other resources are available? ------------------------------------- - 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 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 ftp.desy.de [131.169.10.115] and get the file: /pub/userWWW/projects/Announce/LitProg.txt - ---------------------------------------------------------------------- - TeX Resources --------------- Another resource of interest to literate programmers is the info-tex mailing list. If you're using (La)TeX as your typsetting system and have access to internet, then you should investigate this mailing list. Mail list service is available through the SHSU list-server. To subscribe, send a message to LISTSERV@SHSU.EDU, and include in the message one line of text: SUBSCRIBE INFO-TEX "your name in quotes" The list is unmoderated; messages sent to info-tex@shsu.edu are automatically distributed to all subscribers and cross-posted to comp.text.tex. Archives of the mailing list and newsgroup are maintained on niord.shsu.edu [192.92.115.8] in the directory info-tex. 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. - ---------------------------------------------------------------------- - Virtual Coursework -------------------- Marcus Speh plans an introductory course on Literate Programming on the Internet, part of the first semester of "Global Network Academy" [GNA], a non-profit corporation incorporated in the state of Texas, affilated with the Usenet University project. The texts/sample programs for this class will be made available via the World-Wide Web. A special room on GNA Virtual Campus will be staffed by a consultant in one to two hour shifts. Students with questions can telnet to the virtual campus and ask questions of the staff there. If you are interested in registering for the course either as a student or as a consultant, please contact marcus@x4u.desy.de. You will receive a standard reply message; no further action will be taken until June 94. Interested parties can check the hypertext notes for the completed C++ Course done in a similar fashion, at URL http://info.desy.de:80/pub/uu-gna/html/cc/index.html [Editor's note: Because of workload, Marcus requests that email inquiries be limited to a statement of interest for either a student or consultant position until June 1994.] = ====================================================================== * 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: bart.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 written in (Levy/Knuth) CWEB. More details in the distribution. It is available via anonymous ftp from: labrea.stanford.edu:/pub/sgb = ====================================================================== * 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 several 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. = ====================================================================== * 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. = ====================================================================== * 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. = ====================================================================== * 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. = End of File ========================================================== ----- ================================================================================ Archive-Date: Mon, 06 Feb 1995 13:31:13 CDT Sender: owner-litprog@SHSU.edu From: neeri@iis.ee.ethz.ch (Matthias Neeracher) Reply-To: LitProg@SHSU.edu, neeri@IIS.EE.ETHZ.CH Subject: Re: Spidery WEB for Perl? Date: 06 Feb 1995 16:29:34 GMT Message-ID: To: LitProg@SHSU.EDU In article , maavl@cwi.nl (Marc van Leeuwen) writes: > In article <3grp1v$i4r@elna.ethz.ch>, neeri@iis.ee.ethz.ch (Matthias > Neeracher) writes: > |> diego@ds5000.dgsca.unam.mx (Diego Zamboni) writes: > |> > Has somebody done something with Spidery Web for programming in > |> >perl? Or does anybody know of some literate programming tool > |> >apt for programming in perl? > |> > |> I'd recommend noweb. Perl syntax is quite complex to parse, so you'd > |> probably spend more time fiddling with pretty-printing than programming > |> (Of course, the fact that this argument is mostly applicable to *every* > |> programming language is exactly what made Norman Ramsey write noweb based > |> on his experiences with Spidery WEB - or that's the impression I got from > |> his papers). > You may be right for Perl, but I disagree for the claim about every > programming language. Just recently I wrote a spidery web for the GAP > (computer algebra) language, which took me no more than two days, including > the installation of Spidery WEB itself (that was the hardest part, it comes > with the most horrid makefile I have ever had to look at), and playing > around a bit with various layout styles; it works like a charm. I was not trying to imply that Spidery WEB doesn't do its job. > It all depends very much on the particular language you are using. [...] > [...] Just as an indication, in my opinion Pascal would be > fine, C is on the border, and C++ would be over the border (too much context > dependence), at least, if you are serious about the full langauge and > quality pretty printing. Yes, that agrees quite well with my (limited) personal experience. But even when the grammar works well, users of prettyprinting Webs still have to provide formatting hints like @; or @#. > Nevertheless I strongly disagree with people saying that pretty-printing is > not worth the effort for anyone in general; this depends very much on ones > particular situation and purpose. In some cases pretty-printing may even be > the main reason to opt for literate programming. What I like about noweb is that it doesn't *totally* close the door for all future prettyprinting. It always leaves at least a theoretical possibility to add a prettyprinter to the system. This helps to stop worrying about prettyprinting while programming. Matthias ----- Matthias Neeracher http://err.ethz.ch/members/neeri.html "And that's why I am going to turn this world upside down, and make of it a fire so *bright* that someone real will notice" -- Vernor Vinge, _Tatja Grimm's World_ ================================================================================ Archive-Date: Mon, 06 Feb 1995 22:15:46 CDT Sender: owner-litprog@SHSU.edu From: norman@flaubert.bellcore.com (Norman Ramsey) Reply-To: LitProg@SHSU.edu, norman@FLAUBERT.BELLCORE.COM Subject: Re: Clueless questions about literate programming are welcome here Date: 6 Feb 1995 18:04:13 GMT Message-ID: <3h5oat$i2e@lowell.bellcore.com> To: LitProg@SHSU.EDU In article , Ryan Davis wrote: >3) Is there any implementations of *WEB* that are macintosh compatible, OR >that are machine independant and will run with PERL or some other widely >available language? noweb, nuweb, and Funnelweb will let you write programs in any language. I think nuweb jsut works on Macs. Getting noweb installed on a Mac would be quite a chore. Norman ================================================================================ Archive-Date: Tue, 07 Feb 1995 01:54:46 CDT Sender: owner-litprog@SHSU.edu From: gurari@cis.ohio-state.edu (Eitan Gurari) Reply-To: LitProg@SHSU.edu, gurari@CIS.OHIO-STATE.EDU Subject: Re: Clueless questions about literate programming are welcome here Date: 7 Feb 1995 02:50:46 -0500 Message-ID: <3h78omINNeaq@sunkist.cis.ohio-state.edu> To: LitProg@SHSU.EDU ..In article , ..Ryan Davis wrote: ..>3) Is there any implementations of *WEB* that are macintosh compatible, OR ..>that are machine independent and will run with PERL or some other widely ..>available language? .. ..noweb, nuweb, and Funnelweb will let you write programs in any ..language. I think nuweb just works on Macs. Getting noweb installed ..on a Mac would be quite a chore. (Al)ProTex provides another alternative, if you have (La)TeX on your system. No installation is required besides ftp'ing two files. ..4) I've noticed several *WEB* thingies are C, C++, Pascal...... ..literate(?) but never have I seen the word smalltalk... anyone? Trygve Reenskaug and Anne L. Skaar. An Environment for Literate Smalltalk Programming. Proceedings of the 1989 Conference on Object-Oriented Programming: Systems, Languages, and Applications, ACM SIGPLAN Notices 24:10 (1989), 337--345. ================================================================================ Archive-Date: Tue, 07 Feb 1995 13:19:01 CDT Sender: owner-litprog@SHSU.edu From: weiqigao@crl.com (Weiqi Gao) Reply-To: LitProg@SHSU.edu, weiqigao@CRL.COM Subject: Re: Cdrom Package Date: 5 Feb 1995 05:16:16 GMT Message-ID: <3h1mv0$4l0@nntp.crl.com> MIME-Version: 1.0 To: LitProg@SHSU.EDU In article <3h1dln$vu6@omnifest.uwm.edu>, nkirsch@omnifest.uwm.edu says... > >There's a new cdrom package/book out that tells you how to create games like >doom. If anyone has heard about it can you please post some info about it >here. =|:-)= HUH? ================================================================================ Archive-Date: Tue, 07 Feb 1995 19:46:45 CDT Sender: owner-litprog@SHSU.edu From: johnm10657@aol.com (JohnM10657) Subject: VB Mod player! Date: 7 Feb 1995 20:21:28 -0500 Message-ID: <3h96ao$7t9@newsbf02.news.aol.com> Reply-To: LitProg@SHSU.edu, johnm10657@aol.com (JohnM10657) To: LitProg@SHSU.EDU I was woundering if any one has a .mod or .s3m player writen in Visual Basic that I could look at to see if I can make a mod player for windows. I have looked almost everyware and no one seams to have much VB stuf. All I can find are MIDI and WAV players. Is thare a mod player out there that includes the source code for Visual Basic? Am I wasting my time looking for one? If you know of one please write back! THANKS! ================================================================================ Archive-Date: Tue, 07 Feb 1995 23:36:21 CDT Sender: owner-litprog@SHSU.edu From: schrod@iti.informatik.th-darmstadt.de (Joachim Schrod) Reply-To: LitProg@SHSU.edu, schrod@ITI.INFORMATIK.TH-DARMSTADT.DE Subject: Re: Spidery WEB for Perl? Date: 7 Feb 1995 12:02:28 GMT Message-ID: <3h7ngk$sb1@rs18.hrz.th-darmstadt.de> To: LitProg@SHSU.EDU In article , neeri@iis.ee.ethz.ch (Matthias Neeracher) writes: > > Yes, that agrees quite well with my (limited) personal experience. But even > when the grammar works well, users of prettyprinting Webs still have to > provide formatting hints like @; or @#. IMO that's because the prettyprinting grammars are so bad. In particular: -- Most often one has to use `@;' after refinements. That's not needed if the grammar recognizes a rule like `refinement LINE_END -> statement', i.e., if a refinement at the end of the line implies a `@;' behind. -- Most grammars try to be too cute anyhow. If we look at the success of font-lock or hilit in the Emacs world, we can see that users want prettyprinting, but they want only a _limited_ amount of it. IMO, the prettyprinter shall not mangle their input and make it unreadable (e.g., CWEB would do this all the time with my programs...). Instead it should _augment_ the input with typographic information. In the moment, when a prettyprinter takes the input code structure created by the author as a very serious hint for the output, users don't flame the system any more. Empower the user! I agree with the final comment on noweb, though. Did anybody write a converter for CWEB -> noweb? Joachim PS: cweb-mode of Christian is available at the LitProg Archive. I don't know why my automatic regular posting about the Archive contents did not appear this month. Have to check this, sigh. -- =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= Joachim Schrod Email: schrod@iti.informatik.th-darmstadt.de Computer Science Department Technical University of Darmstadt, Germany ================================================================================ Archive-Date: Wed, 08 Feb 1995 08:06:43 CDT Sender: owner-litprog@SHSU.edu From: cjmb@signal.dra.hmg.gb (Christopher Booth) Subject: Re: Separate Compilation Date: 8 Feb 1995 10:25:56 GMT Message-ID: <3ha67k$9un@signal.dra.hmg.gb> Reply-To: LitProg@SHSU.edu, cjmb@signal.dra.hmg.gb To: LitProg@SHSU.EDU In article <1995Jan30.200706.26129@wisipc.weizmann.ac.il>, oren@hadar.weizmann.ac.il (Ben-Kiki Oren) writes: > >Well, I've downloaded noweb and nuweb off the net and looked into both. Both >are nice, but probably noweb is the tool for me since both are (alas!) >inadequate to my needs, as it is designed to be easily extendible. I'll >probably look into the new FWEB release since it supports HTML (which is my >target formatter). I'm ``somewhat unhappy'' with LaTeX2HTML. > >At any rate, my problem is that both tools have zilch support for separate >compilation. Now, I typically place each C++ class in its own set of .hh/.cpp >files (with a possible .ii for inlines, etc.). I naturally want to write a >single '.w' file per class. >So, is there some blessed soul who has already implemented such a scheme? >If not, has literate programming ever been implemented for projects with >a multitude of cross-referencing source files worked on by multiple >programmers? How did they do it, then? Am I missing something obvious? > Seconded. I too have used noweb to write C++ in separate classes like this, and you would gasp to see the kludgy way I have tried to get around this problem. It does seem as though it should be possible to address the issue of referencing other WEB documents without physically including them at the level of WEB code (in whatever dialect :-). Chris. -- ----------------------------------------------------------- Parallel Processing Section | Christopher Booth email: cjmb@signal.dra.hmg.gb | DRA Malvern Fax: +44 (684) 894389 | St Andrews Road Tel: +44 (684) 896400 | Malvern. WR14 3PS UK ----------------------------------------------------------- ================================================================================ Archive-Date: Wed, 08 Feb 1995 11:14:20 CDT Sender: owner-litprog@SHSU.edu From: kumpf@igd.fhg.de (Christian Kumpf smurf) Reply-To: LitProg@SHSU.edu, kumpf@IGD.FHG.DE Subject: Cweb Mode V2.1 Date: 06 Feb 1995 17:53:58 GMT Message-ID: To: LitProg@SHSU.EDU Recently posted to gnu.emacs.sources: (C-)WEB-Mode V2.1 ************ Cweb-Mode is a minor mode to support literate programming in GNU-Emacs Version 19. Main changes since V1.0: * Support of different programming languages than C. Currently C, C++, Pascal, and FORTRAN are supported. * Extended menu and indexing features. * Improved highlighting. * Added '@'-keystrokes. * Workarounds for older GNU Emacses. * Automatic installation. ------------------------------------------------------------------------ (C-)WEB-Mode ************ Cweb-Mode is a minor mode to support literate programming in GNU-Emacs Version 19. FILES: cweb-mode.el (the main program in emacs-lisp) cweb-mode.texi (the user manual in texinfo-format) cweb-install.el (automatic installation) cweb-x11.el (X11-support) cweb-fix-24.el (support for emacses below 19.25) cweb-conf.el (basic configuration) cweb-c.el (C-language configuration) cweb-c++.el (C++-language configuration) cweb-pascal.el (Pascal-language configuration) cweb-fortran.el (FORTRAN-language configuration) LCD-entry (entry for Lisp Code Directory) README (this file) To get full documentation, run cweb-mode.texi either through texi2dvi for a printable manual or through makeinfo for online help. ------------------------------------------------------------------------ Initial Installation ==================== UNIX users should simply enter `emacs -l cweb-install.el' in the shell and follow the prompts. Users on other operating systems should first copy the files `cweb-*.el' to a location, where your Emacs finds them, then byte--compile them, and add the lines (defvar cweb-prog-language "C" "*String used in mode line to indicate programming parts, loading language specific configuration is also based on this variable.") (make-variable-buffer-local 'cweb-prog-language) (autoload 'cweb-mode "cweb-mode" "Toggle cweb mode. With arg, turn cweb mode on iff arg is positive." t) either to your `.emacs'-- or to your `.../site-lisp/default.el'--file. ------------------------------------------------------------------------ Taken from cweb-mode.texi: Features ======== Like every literate programer, I appreciate the different treatment of *C*- and TeX-parts in a CWEB-document. But I missed support for different kinds of writing in my favorite editor. So here it is * *C-mode*-like editing in C-parts of a program * (La)TeX-like editing in documentation-parts of a program * Hilighting of program-parts * CWEB-orientated cursor movement * Indexing of your refinements and your main sections, even for multiple input files * Support of arbitrary programming languages Why a Minor Mode ================ First of all, it's less work :-). But more seriously, writing a major mode would have the drawback of disabling the advanced features of major modes designed by others to enhance Emacs treatment of TeX input. It would reduce flexibility too, because it would be either a TeX or a LaTeX mode. Bug Reports =========== I strongly encourage every user of Cweb Mode to report bugs, suggestions, enhancements, goals, ideas, acknowledgements, for short everything that belongs to Cweb Mode via e-mail to me personally. My e-mail-adress is `kumpf@igd.fhg.de' -- Christian Kumpf IGD Fraunhofer Graphic Research Center Department 1 (Document Imaging) Phone: -49-6151-155-102 Wilhelminenstrasse 7 D-64283 Darmstadt Germany email: kumpf@igd.fhg.de ================================================================================ Archive-Date: Wed, 08 Feb 1995 12:23:02 CDT Sender: owner-litprog@SHSU.edu From: cm1bcnsh@bs47c.staffs.ac.uk (unknown) Reply-To: LitProg@SHSU.edu, cm1bcnsh@BS47C.STAFFS.AC.UK Subject: Re: Screen Saver Date: 8 Feb 1995 16:11:40 GMT Message-ID: <3haqfs$p5m@bs33n.staffs.ac.uk> To: LitProg@SHSU.EDU NinKid (ninkid@aol.com) wrote: : DOS Screen Savers vary GREATLY from Windows screen savers. The two are : completely different formats. If you want to know how to program a : screen saver for DOS, just e-mail me. I have very little experience in : Windows so don't ask me about Windows. : NinKid@aol.com ================================================================================ Archive-Date: Wed, 08 Feb 1995 12:48:41 CDT Sender: owner-litprog@SHSU.edu From: neal@ctd.comsat.com (Neal Becker) Reply-To: LitProg@SHSU.edu, neal@CTD.COMSAT.COM Subject: noweb for latex2e? Date: 08 Feb 1995 17:59:56 GMT Message-ID: To: LitProg@SHSU.EDU I am just trying out noweb. It looks pretty good, but I'd like to have a version that generates latex2e, so I can more easily use some of my favorite latex2e stuff (amslatex...) Has anyone done this? ================================================================================ Archive-Date: Wed, 08 Feb 1995 16:37:21 CDT Sender: owner-litprog@SHSU.edu From: schrod@iti.informatik.th-darmstadt.de (Joachim Schrod) Reply-To: LitProg@SHSU.edu, schrod@ITI.INFORMATIK.TH-DARMSTADT.DE Subject: Re: Clueless questions about literate programming are welcome here Date: 7 Feb 1995 20:58:44 GMT Message-ID: <3h8mu4$11nm@rs18.hrz.th-darmstadt.de> To: LitProg@SHSU.EDU In article <3h0f99$6dl@ionews.io.org>, ptjm@io.org (Patrick TJ McPhee) writes: > > % 3) Is there any implementations of *WEB* that are macintosh compatible, OR > % that are machine independant and will run with PERL or some other widely > % available language? > There's an MPW litprog tool, which I suppose is in the archive at Darmstadt. [I haven't seen the original posting, so I'm responding here.] Currently available for Macs (excerpt from the README): cweb - port of CWEB Impact - CTANGLE with Apple-events LPW - Literate Programming Workshop ATTENTION: This is shareware!! [50 US-$] *SpiderWEB* - port of SpiderWEB, for MPW at the LitProg Archive (see below) in machines/mac/. I welcome more contributions. These are no language independent tools that you can use with Perl, though. My bet is that your best try is to port nuweb -- and send me the result for incorporation in the Archive... :-) Cheers, Joachim -- =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= Joachim Schrod Email: schrod@iti.informatik.th-darmstadt.de THD Literate Programming Archive, maintainer ftp.th-darmstadt.de:/pub/programming/literate-programming/ ================================================================================ Archive-Date: Wed, 08 Feb 1995 19:37:36 CDT Sender: owner-litprog@SHSU.edu From: dougs77697@aol.com (DougS77697) Subject: Description updated Date: 8 Feb 1995 20:12:32 -0500 Message-ID: <3hbq60$mf2@newsbf02.news.aol.com> Reply-To: LitProg@SHSU.edu, dougs77697@aol.com (DougS77697) To: LitProg@SHSU.EDU Just thought you might like to know, the AOL description of this group now reads. comp.programming.literate: Literate programs and programming tools. By the way not all of us are newbies, just don't like to pay a $300 a month phone bill for an out if town service provider. ================================================================================ Archive-Date: Wed, 08 Feb 1995 20:36:40 CDT Sender: owner-litprog@SHSU.edu From: norman@flaubert.bellcore.com (Norman Ramsey) Reply-To: LitProg@SHSU.edu, norman@FLAUBERT.BELLCORE.COM Subject: Re: Spidery WEB for Perl? Date: 8 Feb 1995 23:35:58 GMT Message-ID: <3hbkgu$jph@lowell.bellcore.com> To: LitProg@SHSU.EDU In article , Matthias Neeracher wrote: >What I like about noweb is that it doesn't *totally* close the door for all >future prettyprinting. It always leaves at least a theoretical possibility to >add a prettyprinter to the system. This helps to stop worrying about >prettyprinting while programming. Adding prettyprinters to noweb is more than just a possibility. Kostas Oikonomou has done it for Icon, Turing, and some other languages. Kaelin Colclasure did one for C++. These prettyprinters are included in the noweb distribution. Norman ================================================================================ Archive-Date: Thu, 09 Feb 1995 03:13:02 CDT Sender: owner-litprog@SHSU.edu From: drh@daleth.cs.princeton.edu (Dave Hanson) Reply-To: LitProg@SHSU.edu, drh@DALETH.CS.PRINCETON.EDU Subject: lcc-An example of a large literate program Message-ID: <1995Feb8.153057.995@Princeton.EDU> Date: Wed, 8 Feb 1995 15:30:57 GMT To: LitProg@SHSU.EDU lcc is a retargetable compiler for ANSI C with code generators for the SPARC, MIPS R3000, and Intel x86. The just-published book A Retargetable C Compiler: Design and Implementation. Christopher W. Fraser and David R. Hanson. Benjamin/Cummings, 1995. ISBN 0-8053-1670-1. is a detailed tour of the implementation of lcc. The entire book is a "literate program" -- the source code is intermingled with the descriptive text. The book was produced with the noweb, a low-tech literate programming system. Single copies may be ordered directly from the Benjamin/Cummings Order Dept. at 800-447-2226, and are available in bookstores. lcc is available for anonymous ftp from ftp.cs.princeton.edu in pub/lcc; the README file there gives acquisition details. The distribution includes the source code for the complete compiler and the code-generator generator. More information about lcc is available on the WWW at URL http://www.cs.princeton.edu/software/lcc. Chris Fraser, AT&T Bell Labs Dave Hanson, Princeton Univ. 2/8/95 ================================================================================ Archive-Date: Thu, 09 Feb 1995 09:22:52 CDT Sender: owner-litprog@SHSU.edu From: ccapc@cyber.sell.com (Consumer Credit Advocates) Reply-To: LitProg@SHSU.edu, ccapc@CYBER.SELL.COM Subject: GUARANTEED CREDIT REPAIR BY LAW FIRM Date: 9 Feb 1995 06:11:16 -0500 Message-ID: <3hct8k$t4u@panix.com> To: LitProg@SHSU.EDU Consumer Credit Advocates, PC 11 Pennsylvania Plaza, Suite 2101 New York, NY 10001 (212) 629-5261 (telephone) (212) 629-4762 (fax) E-MAIL: ccapc@cyber.sell.com Our LAW FIRM offers direct guaranteed effective credit restoration services by experienced attorneys. THIS IS NOT A DO-IT-YOURSELF KIT. What can we do? We have successfully facilitated the removal of Late Payments, Charge-offs, Foreclosures, Repossessions, Collection Accounts, Loan Defaults, Tax Liens, Judgments and Bankruptcies from our clients' credit reports. WE GUARANTEE THAT YOUR CREDIT CAN BE RESTORED!!! Who needs our services? Anyone who has experienced the inconvenience and embarrassment of being turned down for a credit card, a lease or a purchase of an automobile. Anyone who is unable to buy the house of their dreams due to denial of a mortgage application or who has to pay thousands of dollars more in mortgage interest than someone with good credit. Anyone who has been turned down for a job or promotion due to derogatory credit items on a credit report. Anyone in business who has lost a deal because a person or firm wanted to see his/her credit report before doing business. Anyone who has been unable to establish credit. THE FOUR GREAT MYTHS OF CREDIT: Myth #1: It is illegal or immoral to have your credit report cleared. Fact: It is not illegal nor immoral. In fact, that is what the Fair Credit Reporting Act is all about. The act was enacted by Congress in 1971. One of its purposes as to give consumers the protection of the law and to help guard against any unwarranted invasion of a consumer's right to privacy. Myth #2: The information on a credit report cannot be changed. Fact: Actually, the opposite is true under the Fair Credit Reporting Act. Federal and State laws require that items be removed if they are not 100% accurate or cannot be verified in a timely manner. Myth #3: It is impossible to get a bankruptcy off a credit report. Fact: Bankruptcies can come off credit reports like any other derogatory item. The nature of the derogatory item has nothing to do with its removal under the Fair Credit Reporting Act. Myth #4: Credit Reporting Agencies are empowered with some kind of governmental authority. Fact: Absolutely Not!! They are simply large corporations whose primary goal is to make a profit like any other business. If you have ever applied for or received credit, a file exists in one or more of the credit bureaus. These companies collect, store and distribute as much credit information as they can find, retaining negative information on a credit report for 7 to 10 years. This information is evaluated by potential creditors to determine your credit worthiness. Credit reporting agencies are in business to protect the interests of the creditors. the LAW FIRM's goal is to help and protect the individual consumer from inaccurate credit reporting. The president of our LAW FIRM has been practicing consumer law since 1984. The staff of our firm has successfully processed, disputed and challenged thousands of client credit reports. Our legal fee is based o the number of negative items that appear on a client's credit reports, issued b the three national credit bureaus. Our retainer agreement offers a MONEY BACK GUARANTEE stating that if any negative item is not deleted, upgraded or corrected from a client's credit file, it will give the client a full refund for that item or continue to process the client's file at no additional fee until that item is corrected, upgraded or deleted. THE ONLY THING YOU HAVE TO LOSE IS YOUR BAD CREDIT!! PLEASE CONTACT THE LAW FIRM AND LEAVE YOUR FULL NAME, MAILING ADDRESS AND TELEPHONE NUMBER SO WE MAY FORWARD FURTHER INFORMATION AND INSTRUCTIONS TO YOU ABOUT OUR SERVICE. Consumer Credit Advocates, PC 11 Pennsylvania Plaza, Suite 2101 New York, NY 10001 (212) 629-5261 (telephone) (212) 629-4762 (fax) E-MAIL: ccapc@cyber.sell.com ================================================================================ Archive-Date: Thu, 09 Feb 1995 10:05:16 CDT Sender: owner-litprog@SHSU.edu From: creilly@maths.tcd.ie (Colman Reilly) Reply-To: LitProg@SHSU.edu, creilly@MATHS.TCD.IE Subject: Re: noweb for latex2e? Date: 9 Feb 1995 10:49:43 -0000 Message-ID: <3hcs07$5qn@bell.maths.tcd.ie> To: LitProg@SHSU.EDU neal@ctd.comsat.com (Neal Becker) writes: >I am just trying out noweb. It looks pretty good, but I'd like to >have a version that generates latex2e, so I can more easily use some >of my favorite latex2e stuff (amslatex...) >Has anyone done this? I'm using noweb with latex2e ... just tell it not to produce the wrappers and include them yourself, including the \usepackage{noweb} if you need it. All seems to work nicely, except for some bad line breaks with the [[]] construction. (Why doesn't that wrap properly?) Colman -- Colman Reilly (creilly@maths.tcd.ie) [+353-(0)1-7022280] c/o School of Mathematics,18.05 Westland Row,Trinity College,Dublin. PGP Public Key on Request MIME OK "Nothing so strong as gentleness; nothing so gentle as real strength." ================================================================================ Archive-Date: Fri, 10 Feb 1995 10:58:06 CDT Sender: owner-litprog@SHSU.edu From: nkirsch@omnifest.uwm.edu (Nick F. Kirsch) Reply-To: LitProg@SHSU.edu, nkirsch@OMNIFEST.UWM.EDU Subject: Re:CD-ROM Date: 9 Feb 1995 16:12:12 -0600 Message-ID: <3he3vs$n3a@omnifest.uwm.edu> To: LitProg@SHSU.EDU Sorry for posting that message about that cdrom package but that what i thought it was for and i read the faq but i did not know how to get the faq's before ================================================================================ Archive-Date: Fri, 10 Feb 1995 11:05:03 CDT Sender: owner-litprog@SHSU.edu From: anwrtbeer@aol.com (ANWRtbeer) Subject: HELP!! Need info Date: 10 Feb 1995 00:17:17 -0500 Message-ID: <3hesst$d13@newsbf02.news.aol.com> Reply-To: LitProg@SHSU.edu, anwrtbeer@aol.com (ANWRtbeer) To: LitProg@SHSU.EDU Hi. I'm trying to help a friend find a computer programming job. However, I'm confused on many things. 1) What is Oracle? Is it Dos Based 2) What is RPG, C, and/or C++? 3) Where can I purchase C, C++, or Oracle...or any language. 4) What is the future outlook for computer programming? I'd like any info that anyone can give me. Please e-mail me at my address on AOL. It is ANWRtbeer@aol.com (after the rootbeer) Amanda Williams ================================================================================ Archive-Date: Fri, 10 Feb 1995 14:40:11 CDT Sender: owner-litprog@SHSU.edu Date: Thu, 09 Feb 1995 18:54:00 -0700 (PDT) From: "Stephen Boyan (510) 926-3291/fax 926-3604" Reply-To: LitProg@SHSU.edu, BOYANST@NCAL.KAIPERM.ORG Subject: RE: Description updated To: LitProg@shsu.edu > literate programming and programming tools [in AOL description of group] the first part of this is going to look like a generic term to people unfamiliar with the subject the second half of this phrase is still going to attract people looking for free C compilers and what not; it isn't clear that programming tools means tools for _literate_ programming I'd like to see AOL add a sentence defining literate programming as a coding and design practice that combines documentation and source in the same file ================================================================================ Archive-Date: Fri, 10 Feb 1995 15:47:22 CDT Sender: owner-litprog@SHSU.edu From: casiello@novalink.com (Brian Casiello) Reply-To: LitProg@SHSU.edu, casiello@NOVALINK.COM To: litprog@shsu.edu Subject: Re: Description updated Date: Fri, 10 Feb 95 16:38:52 EST Message-ID: dougs77697@aol.com (DougS77697) writes: > Just thought you might like to know, the AOL description of this group > now reads. > > comp.programming.literate: > > Literate programs and programming tools. Good news about the update, unless we start getting: D00DZ: I NEED S0ME WAR3Z 2 TEECH ME AB0UT SHAK3SP3AR3 & CHARL3S D1CK3NS B1FF > By the way not all of us are newbies, ... I don't think it's the newbies that are necessarily the problem; if AOL is disseminating inaccurate or incorrect information that newbies are accepting and acting on, it's AOL's fault, not the newbie's. Does AOL post any netiquette suggestions? (i.e. Read the FAQ, and the group for a while before posting) If they don't, it would probably be helpful for them to do so. But... can't we flame you, anyway? Just a little bit? Pleeze? -- Brian "Former Internet Newbie" Casiello Worcester MA USA Does that make me an Oldbie?" ================================================================================ Archive-Date: Fri, 10 Feb 1995 18:01:46 CDT Sender: owner-litprog@SHSU.edu From: cs151er2@lamar.ColoState.EDU (Thomas "22" Miller) Reply-To: LitProg@SHSU.edu, cs151er2@LAMAR.COLOSTATE.EDU Subject: Need help on reading text in serial port Date: 10 Feb 1995 16:22:30 -0700 Message-ID: <3hgsfm$etu@lamar.ColoState.EDU> To: LitProg@SHSU.EDU I am trying to read in ASCII from a piece of scientific equipment throught the serial port of my PC. The data is transfered through an RS-232 port from the analyzer to the PC. I want to open a text file and dump all the information from the analyzer into it. The text file will later be opened by MS Access. Any help would be greatly appreciated. Thanks in advance, Tom Miller tmiller@vines.colostate.edu ================================================================================ Archive-Date: Sat, 11 Feb 1995 15:26:23 CDT Sender: owner-litprog@SHSU.edu From: gurari@cis.ohio-state.edu (Eitan Gurari) Reply-To: LitProg@SHSU.edu, gurari@CIS.OHIO-STATE.EDU Subject: Re: Clueless questions about literate programming are welcome here Date: 11 Feb 1995 15:55:10 -0500 Message-ID: <3hj87eINNl16@sunkist.cis.ohio-state.edu> To: LitProg@SHSU.EDU ..> % 3) Is there any implementations of *WEB* that are macintosh compatible, OR ..> % that are machine independant and will run with PERL or some other widely ..> % available language? ..> There's an MPW litprog tool, which I suppose is in the archive at Darmstadt. ..[I haven't seen the original posting, ....... And the one I had :-( ..These are no language independent tools that you can use with Perl, ..though. My bet is that your best try is to port nuweb -- and send me ..the result for incorporation in the Archive... :-) .. ..Cheers, .. Joachim The following example illustrates what it takes to compile noweb files with protex (for any tab-free program on any platform that supports (la)tex). No need to add protex to the archive, it is already there ;-) -eitan ------------------ example of a latex file --------------------- % Requires LaTeX, (Al)ProTex, the file `noweb.sty' from % bellcore.com : pub/norman/noweb/tex/ and the following files from % bellcore.com : pub/norman/noweb/examples/ % % breakmodel.nw dag.nw graphs.nw mipscoder.nw % multicol.sty primes.nw scanner.nw test.nw % tree.nw wc.bbl wc.nw README % % Changes needed within the `.nw' files % % 1. Insert `@' after each chunk that is not delimited with such a character % 2. Replace `@<<' with `<@<' % 3. Clean ``[[...]]'' from special characters that differ from ^ and _ \documentstyle{book} %----------- ProTeX adjusted to accept noweb inputs ------- \input ProTex.sty \catcode`\^^M=13 \def\CodeDel{{=}{ @}} \catcode`\^^M=5 \AlProTex{any,<<<>>>,title,list,ClearCode,_^,ShowFile,[]} \let\oldModifyAppendCode=\ModifyAppendCode \let\oldModifyOutputCode=\ModifyOutputCode \def\ModifyAppendCode#1{\oldModifyAppendCode{#1}\catcode`\<=13 \catcode`\\=12\relax} \def\alprotextitle#1#2>>{\egroup \<#2\>} \def\alprotextitleA#1#2>>{\<#2\>} \def\ltsym{<} \catcode`\<=13 \def<#1{\ifx#1<\bgroup \catcode`\$=12 \catcode`\\=12 \par \expandafter\alprotextitle \else \expandafter\ltapsym\fi #1} \def\ltapsym#1{\ltsym\ifx#1@\else\expandafter#1\fi} \def\ModifyOutputCode{\def<##1{\ifx##1<\expandafter\alprotextitleA \else \expandafter\ltapsym\fi ##1}\oldModifyOutputCode} %------------------------------------------------- \textwidth=6.9in \oddsidemargin=0pt \evensidemargin=0pt \begin{document} \tableofcontents %---------- noweb style files -------------------- \catcode`\@=11 \catcode`\^=7 \input multicol.sty \input noweb.sty \catcode`\@=12 \catcode`\^=13 %-------------- tame [[...]] -------------------- \def\oldcite{\@tempswafalse \@citex []} \def\bracket{[} \catcode`\[=13 \def[{\bracket} \def\cite{\@ifnextchar [{\@tempswatrue \@citex }{\oldcite}} %---------------- README ------------------------- \chapter{README} \ShowFile{README} \let\oldinput=\input \def\input#1.#2 {\chapter{#1}\openin15=#1.#2 \ifeof15 \closein15 \immediate\write16{-----File ``#1.#2'' is missing-----} \else \oldinput #1.#2 \fi} %---------------- breakmodel --------------------- \input breakmodel.nw \ClearCode %----------------- dag --------------------------- \input dag.nw <>= <<*>> @ \OutputCode\ \ClearCode %----------------- graphs ------------------------ \begingroup \catcode`\#=12 \catcode`\&=12 \input graphs.nw \endgroup \ClearCode %----------------- mipscoder --------------------- \input mipscoder.nw <>= <<*>> @ \OutputCode\ \ClearCode %----------------- primes ------------------------ \input primes.nw <>= <<*>> @ \OutputCode\ \ClearCode %----------------- scanner ----------------------- \input scanner.nw \OutputCode\ \OutputCode\ \ClearCode %----------------- test -------------------------- \input test.nw <>= <<*>> @ \OutputCode\ \ClearCode %----------------- tree -------------------------- \input tree.nw <>= <<*>> @ \OutputCode\ \ClearCode %----------------- wc ---------------------------- \input wc.nw <>= <<*>> @ \OutputCode\ \ClearCode \end{document} ================================================================================ Archive-Date: Sat, 11 Feb 1995 20:51:34 CDT Sender: owner-litprog@SHSU.edu From: irr000494@interramp.com Reply-To: LitProg@SHSU.edu, irr000494@INTERRAMP.COM Subject: Re: I Want to LEARN! Date: Fri, 10 Feb 95 14:27:46 PDT Message-ID: MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII To: LitProg@SHSU.EDU > >Hello! > > I'm totally new to programming (as if you didn't already > >guess) and I would like to learn some languages for IBM/DOS. I > >just want to start out with something basic. (excuse the pun) > > So If you have any Ebooks, guides, programs etc. that are > >sorta simple and you have the time to email 'em to me, it would > >be much appreciated! > > For the seventh time, this is an inappropriate topic. The > comp.programming.literate group is for the discussion of Literate > Programming---the art of producing a text-processor readable documentation > and compiler readable programming files from the same source file. Thanks for being a complete asshole. You should be happy that people are trying to get into programming. Instead of replying in civil manner, you had to first downgrade the individual. This type of abuse will not increase anyone's desire to programm, if other experienced programmers as jerks. A. Quinn ir000494@interramp.com ================================================================================ Archive-Date: Sun, 12 Feb 1995 10:14:50 CDT Sender: owner-litprog@SHSU.edu From: rread@diogenes.com (Robert M. Read) Subject: Lit prog and Modula-3 Date: 12 Feb 1995 09:14:53 GMT Message-ID: <3hkjie$2oo@condor.ic.net> Reply-To: LitProg@SHSU.edu, rread@ic.net To: LitProg@SHSU.EDU Is anyone else out there programming in Modula-3? If so, have you found the m3totex powerful enough to support literate programming, or did you go back to *web? This is a pretty weak question, but at least it is actually about literate progamming. -- Robert M. Read rread@ic.net ================================================================================ Archive-Date: Mon, 13 Feb 1995 07:54:22 CDT Sender: owner-litprog@SHSU.edu Date: Mon, 13 Feb 1995 14:53:48 +0100 (MET) From: Kolma Kornel Reply-To: LitProg@SHSU.edu, s6404kol@SUN10.VSZ.BME.HU To: litprog@shsu.edu Message-ID: MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII subscribe Kolma Kornel ================================================================================ Archive-Date: Mon, 13 Feb 1995 23:41:18 CDT Sender: owner-litprog@SHSU.edu From: iec@netcom2.netcom.com (Interstate Electronics Corp) Subject: Re: Lit prog and Modula-3 Message-ID: Reply-To: LitProg@SHSU.edu, mre@lpf.org (Mike Elliott) Date: Mon, 13 Feb 1995 09:01:49 GMT To: LitProg@SHSU.EDU Is anyone else out there programming in Modula-3? If so, have you found the m3totex powerful enough to support literate programming, or did you go back to *web? Yes, we are. No, I haven't tried m3totex. Modula-3 works just fine with funnelweb, noweb and nuweb (and perhaps others, as well), so I haven't seen a need to try m3totex. This is a pretty weak question, but at least it is actually about literate progamming. Well, you got a pretty weak answer, too. -- ======================================================================== Mike Elliott mre@emerald.ccss.com mre@lpf.org ======================================================================== -- -- ======================================================================== Mike Elliott mre@emerald.ccss.com mre@lpf.org ======================================================================== ================================================================================ Archive-Date: Tue, 14 Feb 1995 00:08:04 CDT Sender: owner-litprog@SHSU.edu From: sp106@york.ac.uk (stephen) Reply-To: LitProg@SHSU.edu, sp106@YORK.AC.UK Subject: Re: Cdrom Package Date: 12 Feb 1995 21:35:43 GMT Message-ID: <3hluvf$rkb@castle.york.ac.uk> To: LitProg@SHSU.EDU Nick F. Kirsch (nkirsch@omnifest.uwm.edu) wrote: : There's a new cdrom package/book out that tells you how to create games like : doom. If anyone has heard about it can you please post some info about it : here. =|:-)= This group is not for literature about programming, but for literate programming. Try alt.comp.boring.games.doom or whatever. stephen. ps. that .sig made we wonder if this was crossposted with alt.fan.warlord. -- #################################################### # sp106@york.ac.uk # http://www.york.ac.uk/~sp106 # # Each set includes a turntable, nine inch icing # # bag, six high definition nozzles... # #################################################### ================================================================================ Archive-Date: Tue, 14 Feb 1995 02:00:34 CDT Sender: owner-litprog@SHSU.edu From: melocin@ccvax.ucd.ie Reply-To: LitProg@SHSU.edu, melocin@CCVAX.UCD.IE Subject: Re: Clueless questions about literate programming are welcome here Message-ID: <1995Feb13.131606.57792@ccvax.ucd.ie> Date: 13 Feb 95 13:16:06 WET To: LitProg@SHSU.EDU In article <3h0f99$6dl@ionews.io.org>, ptjm@io.org (Patrick TJ McPhee) writes: ..... > No. At least in my view, literate programming is a mechanism for writing > programs which are relatively easy to maintain. Apart from encouraging > verbose comments, literate programming places emphasis on explaining how ..... Are verbose comments appropriate? Verbose comments are - tedious to read - spoil the visual structure of the code - are seldom updated by maintainence programmers and so aren't reliable anyway! I always encourage students to write short, terse comments. Well-written code is often self-explanatory and the complexity involved understanding the larger system is better managed by studying the design documentation. I'd agree with 'plenty of appropriate, terse' comments! Regards, Mel O Cinneide ================================================================================ Archive-Date: Tue, 14 Feb 1995 09:09:23 CDT Sender: owner-litprog@SHSU.edu From: dak@messua.informatik.rwth-aachen.de (David Kastrup) Reply-To: LitProg@SHSU.edu, dak@MESSUA.INFORMATIK.RWTH-AACHEN.DE Subject: Re: What is the purpose of literate programming? Date: 14 Feb 1995 08:09:37 GMT Message-ID: <3hpog1$3mu@news.rwth-aachen.de> To: LitProg@SHSU.EDU wongs@unc.edu (Siu-ki Wong) writes: >I am a newie to this news group, so I don't know if this question has >been asked thousands times before. If yes, please excuse for the >redundancy. >If I understand correctly, in this paradigm of programming, we can have >a single source for programs and documentations. Yet, why should we do >that in this way? Is there any advantages in doing so? What is its >impact on the software development and maintenance? >Thanks. It's the program documentation which sits in the same file, not (necessarily) the user's documentation. The purpose is clear: by having the code and code comments appear at the same place, it is psychologically more annoying to have them disagree, so docs and code tend to be more in sync. Also, being able to explain each code part as a separete entity, even if it is not a function, is a definite plus. Especially for programs for mathematical purposes, it is often handy to be able to use all the capabilities for formulas your typesetting system supports in comments. But I'm babbling. See the FAQ which is posted on a frequent basis here. -- David Kastrup, Goethestr. 20, D-52064 Aachen Tel: +49-241-72419 Email: dak@pool.informatik.rwth-aachen.de Fax: +49-241-79502 -- David Kastrup, Goethestr. 20, D-52064 Aachen Tel: +49-241-72419 Email: dak@pool.informatik.rwth-aachen.de Fax: +49-241-79502 ================================================================================ Archive-Date: Tue, 14 Feb 1995 09:09:38 CDT Sender: owner-litprog@SHSU.edu From: dak@messua.informatik.rwth-aachen.de (David Kastrup) Reply-To: LitProg@SHSU.edu, dak@MESSUA.INFORMATIK.RWTH-AACHEN.DE Subject: Re: Clueless questions about literate programming are welcome here Date: 14 Feb 1995 08:17:31 GMT Message-ID: <3hpour$3o0@news.rwth-aachen.de> To: LitProg@SHSU.EDU melocin@ccvax.ucd.ie writes: >In article <3h0f99$6dl@ionews.io.org>, ptjm@io.org (Patrick TJ McPhee) writes: >..... >> No. At least in my view, literate programming is a mechanism for writing >> programs which are relatively easy to maintain. Apart from encouraging >> verbose comments, literate programming places emphasis on explaining how >..... >Are verbose comments appropriate? Verbose comments are >- tedious to read >- spoil the visual structure of the code >- are seldom updated by maintainence programmers and so aren't reliable > anyway! Agreed, in part. However, using a literate programming tool, comment sections and code are presented as typographically different entities, so that it is very easy to study just the code, if you do not care for the comments. The comments do not disrupt the code, it is rather so, that the code exemplifies the expos'e made by the "comments". >I always encourage students to write short, terse comments. Well-written >code is often self-explanatory and the complexity involved understanding >the larger system is better managed by studying the design documentation. And the design documentation can be arranged very well between code chunks, in order to explain how they are interlinked. I'd suggest that you get a few example files from some LP tool in printable form (say, a finished .dvi-file), and take a look at it. Also, you might consider both tools which are prettyprinting and those which are not. I tend to find the latter class more appealing to me, and guessing from the comments you made, it might be you'd do so as well. -- David Kastrup, Goethestr. 20, D-52064 Aachen Tel: +49-241-72419 Email: dak@pool.informatik.rwth-aachen.de Fax: +49-241-79502 -- David Kastrup, Goethestr. 20, D-52064 Aachen Tel: +49-241-72419 Email: dak@pool.informatik.rwth-aachen.de Fax: +49-241-79502 ================================================================================ Archive-Date: Tue, 14 Feb 1995 10:39:22 CDT Sender: owner-litprog@SHSU.edu From: maavl@cwi.nl (Marc van Leeuwen) Reply-To: LitProg@SHSU.edu, maavl@CWI.NL Subject: Re: Spidery WEB for Perl? Message-ID: Date: Tue, 14 Feb 1995 14:25:43 GMT To: LitProg@SHSU.EDU In article <3h7ngk$sb1@rs18.hrz.th-darmstadt.de>, schrod@iti.informatik.th-darmstadt.de (Joachim Schrod) writes: |> In article , neeri@iis.ee.ethz.ch |> (Matthias Neeracher) writes: |> > |> > Yes, that agrees quite well with my (limited) personal experience. But even |> > when the grammar works well, users of prettyprinting Webs still have to |> > provide formatting hints like @; or @#. |> |> IMO that's because the prettyprinting grammars are so bad. I can agree with that only partly. To begin with, `@#' just adds a bit of vertical space, a beautification that is never really essential, so nobody should complain about having to insert it; it is just like your average TeX layout control code that lets you improve the output slightly if you feel like it. On the other hand, `@;' is quite different, as its omission may frustrate parsing completely. However, if the prettyprinting grammar is good, one should need `@;' only in connection with tricky macros, where the superficial syntax (i.e., viewing the macro simply as a function call) differs from the actual syntax after expansion of the macro. (Somewhat ironically, in the original WEB for Pascal, `@;' is only required because of the macro mechanism that WEB itself had added.) As cases that are superficially unsyntactical look peculiar to the human eye (usually a semicolon seems to be lacking), programmers will probably be aware of them anyway, and it should not be too much to ask them to type `@;' to make the code look superficially correct; all this _assuming_ a good prettyprinting grammar. |> In particular: |> |> -- Most often one has to use `@;' after refinements. That's not |> needed if the grammar recognizes a rule like `refinement LINE_END |> -> statement', i.e., if a refinement at the end of the line |> implies a `@;' behind. Here you must be referring to CWEB or something derived from it, because IMO the real reason for this problem has nothing to do for WEB systems in general (e.g., it does not apply to Pascal WEB). Rather, it is caused by an error made in converting WEB to CWEB that was never corrected, namely a failure to recognise the fundamentally different roles of semicolons in Pascal and C. In Pascal semicolons separate statements, whether simple (e.g., assignments) or compound, so if any such statement is followed sequentially by another one, a semicolon is required after the first; the requirement still holds if the first statement is a refinement. In other words, in Pascal one has `refinement -> statement' always, without having to consider LINE_END, and without having to use `@;' (either a real semicolon is required after it, or nothing is, e.g., when ELSE follows). In C however, no symbol separates successive statements, but things like assignments are expressions rather that statements, and they only become statements by incorporating a following semicolon. Since refinements almost always stand for (compound) statements, they should be given that category; however in (Levy/Knuth) CWEB they are given the same category as assignments, which is `expression'. This forces one to write a semicolon after each refinement, even though that really becomes a spurious empty statement; if such an empty statement would mess up the real syntax (the compiler would fail) then one has to write `@;' instead. In CWEBx where the category of refinements is `statement', this problem simply does not exist, and you never write a semicolon after a refinement. I find the solution you suggest a bit more dubious. Not that it would make much difference (in the restricted form you suggest), since in practice refinements always come at the end of a line, so that they are always considered to be statements, which is just what I suggested. But from a more fundamental point of view, this solution implies that line ends will be communicated to the parsing mechanism, supplying it with information that the user did not explicitly intend to be sent. Sometimes a line end will indicate something relevant, like the end of a statement, but that information can also be derived from the programming tokens themselves. On the other hand it will often also indicate something completely irrelevant, like the fact that I have approached the right margin of my favorite text window size (which is quite independent of the right margin of the typeset page). In automatic formatting one should avoid interpreting layout features of the source text unless they are so special that the user can always avoid supplying such features inadvertently[1] (e.g., one could imagine blank lines in the program code being automatically converted to `@#', but even there some programmers may feel that this cramps their input style). It is one of the strong points of TeX that one can format the source text quite freely without having to worry about any effect on the printed output; there is one exception, namely spaces, which are sometimes intended to appear in print and sometimes not, and this is immediately one of the most problematic areas of TeX (too many rules about when to ignore spaces and when not). [1] I gather from its documentation that in noweb chunk names always have to fit on a single line. If this is true, I wonder how people can cope with a restriction that is so contrary to the spirit of literate programming. If forced to, I think I would choose to use lines that are twice or more the width of my window, but it would not cease to frustrate me. |> -- Most grammars try to be too cute anyhow. If we look at the |> success of font-lock or hilit in the Emacs world, we can see that |> users want prettyprinting, but they want only a _limited_ amount |> of it. I don't think these features of the crude-but-interactive world of text editing have very much to do with prettyprinting for typeset documents. It may very well be that what people really want is a WYSIWYG literate programming tool with all kinds of interactive bells and whistles (hypertext at the very least), and I will certainly not deny them their pleasure, but I think this is not the true goal of literate programming as it was conceived by Knuth (which is I think writing and _publishing_ the best possible documentation for programs that are worth it, in a form that tries to make it as accessible as possible to other human beings). |> IMO, the prettyprinter shall not mangle their input and make it |> unreadable (e.g., CWEB would do this all the time with my |> programs...). Instead it should _augment_ the input with typographic |> information. In the moment, when a prettyprinter takes the input code |> structure created by the author as a very serious hint for the |> output, users don't flame the system any more. Empower the user! I already explained why I disagree here. Would you say the same about TeX, i.e., that it should augment the typographic information of the source text, taking the input code structure created by the author as a very serious hint for the output? I am very glad that it does not (except in very limited and well defined ways, like treating blank lines as paragraph separators). I would be very much interested examples where CWEB would really make programs unreadable. I can imagine several scenarios: (1) The input causes te parser to choke, resulting in horrendous output (2) CWEB is being used in an inappropriate way, e.g., huge block comments (3) The input style of the programmer is systematic, but differs radically from the (equally systematic) output style of CWEB. (4) The programmer is using a very ad-hoc style, giving visual clues in ways that the prettyprinter is unable to reproduce. I think case (1) is the most common (it is the only one that would support your strong wording), but such cases are only serious when it is impossible to modify the source with some hints so that the parser will succeed. You would not be justified either in complaining about your programs running incorrectly when they still contain syntax errors. I consider the property of being silent by default about such syntactic disasters a serious defect of traditional WEB systems, but it is easy to remedy. The solution for case (2) is obvious, and in cases (3) and (4) the unreadability is really a subjective matter. I don't expect that cases (2) and (4) occur very frequently (perhaps I am being too optimistic here). As regards (3), it would be a good thing however if any popular layout style could be selected as an option to the prettyprinter (just like LaTeX allows selection of a document style independently from its contents); in CWEBx a modest attempt is made in this direction. This approach would makes the program much more an abstract document, and independent of the particular preferences of the programmer, unlike your suggestion, which does just the opposite. Marc van Leeuwen ================================================================================ Archive-Date: Wed, 15 Feb 1995 00:00:32 CDT Sender: owner-litprog@SHSU.edu Message-ID: <9502141956.AA12579@us4rmc.pko.dec.com> Date: Tue, 14 Feb 95 14:58:54 EST From: mulp 14-Feb-1995 1450 -0500 Reply-To: LitProg@SHSU.edu, pettengill@STEVMS.ENET.DEC.COM To: litprog@shsu.edu CC: pettengill@stevms.enet.dec.com Subject: Re: Clueless questions about literate programming are welcome here Mel O Cinneide writes: >Are verbose comments appropriate? Verbose comments are >- tedious to read >- spoil the visual structure of the code >- are seldom updated by maintainence programmers and so aren't reliable > anyway! > >I always encourage students to write short, terse comments. Well-written >code is often self-explanatory and the complexity involved understanding >the larger system is better managed by studying the design documentation. Terse and verbose are in the eye of the beholder. Most novels could be shortened to a dozen pages, and with a library of generic plots could be shortened to a page by simply referencing the plots and subplots by number. However, would one really appreciate these novels more by referring to the notes that indicate the choice and interplay or plot lines? Don Knuth has merged the design documentation and code into one with WEB. While it is certainly true that code changes are often not reflected in the module comments, it is nearly universally true that design documents NEVER represent the code at any point in time in the life of a project. Unless you are dealing TeX or Metafont or SGB where reading the design and reading the code are one and the same. mulp ================================================================================ Archive-Date: Wed, 15 Feb 1995 16:03:36 CDT Sender: owner-litprog@SHSU.edu From: norman@flaubert.bellcore.com (Norman Ramsey) Reply-To: LitProg@SHSU.edu, norman@FLAUBERT.BELLCORE.COM Subject: Re: Spidery WEB for Perl? Message-ID: CC: Joachim Schrod Date: Tue, 14 Feb 1995 21:38:01 GMT To: LitProg@SHSU.EDU In article <3h7ngk$sb1@rs18.hrz.th-darmstadt.de>, Joachim Schrod wrote: >IMO, the prettyprinter shall not mangle their input and make it >unreadable (e.g., CWEB would do this all the time with my >programs...). Instead it should _augment_ the input with typographic >information. The prettyprinters in the noweb contrib directory have this property; they change the ``look'' of keywords, identifiers, and operators without changing their positions on the page. > Did anybody write a converter for CWEB -> noweb? I wrote one years ago for spidery web, which at the time was fairly close to CWEB. It was either a monster sed script or a monster sam script, and I'm not sure if I can find it. It would probably be easier just to modify cweave to emit the representation described in the noweb hacker's guide. -- Norman Ramsey norman@bellcore.com ================================================================================ Archive-Date: Wed, 15 Feb 1995 16:03:40 CDT Sender: owner-litprog@SHSU.edu From: norman@flaubert.bellcore.com (Norman Ramsey) Reply-To: LitProg@SHSU.edu, norman@FLAUBERT.BELLCORE.COM Subject: Clueless questions about literate programming are welcome here Message-ID: Date: Tue, 14 Feb 1995 21:38:21 GMT To: LitProg@SHSU.EDU Some people may have misunderstood an earlier post of mine to be hostile to people who are clueless newbies to literate programming. False, not so. Clueless and all other questions about literate programming are welcome in this newsgroup. The people who are annoying us are the ones who keep asking DOS/Windows programming questions and other things that have nothing to do with literate programming. -- Norman Ramsey norman@bellcore.com ================================================================================ Archive-Date: Wed, 15 Feb 1995 16:04:00 CDT Sender: owner-litprog@SHSU.edu From: niall@hedgehog.demon.co.uk (Niall Teasdale) Reply-To: LitProg@SHSU.edu, niall@HEDGEHOG.DEMON.CO.UK Subject: Re: Clueless questions about literate programming are welcome here Date: Wed, 15 Feb 1995 21:18:23 +0000 Message-ID: <9502152118.AA0009q@hedgehog.demon.co.uk> To: LitProg@SHSU.EDU melocin@ccvax.ucd.ie wrote: : Are verbose comments appropriate? Verbose comments are : - tedious to read : - spoil the visual structure of the code : - are seldom updated by maintainence programmers and so aren't reliable ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ : anyway! : I always encourage students to write short, terse comments. Well-written : code is often self-explanatory and the complexity involved understanding : the larger system is better managed by studying the design documentation. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Interesting. You know maintenance programmers who don't update the comments, but can be bothered to update the design documentation? One of the best things about literate programming styles is the ability to keep some or all of the design documentation inline with the code. It has the potential of reminding programmers that the design document is there to be updated. I'm not saying it will always work, but it maybe has a better chance. Niall. ================================================================================ Archive-Date: Wed, 15 Feb 1995 16:31:47 CDT Sender: owner-litprog@SHSU.edu From: ptjm@io.org (Patrick TJ McPhee) Reply-To: LitProg@SHSU.edu, ptjm@IO.ORG Subject: Re: Clueless questions about literate programming are welcome here Date: 15 Feb 1995 01:17:35 -0500 Message-ID: <3hs69v$5e8@ionews.io.org> To: LitProg@SHSU.EDU In article <1995Feb13.131606.57792@ccvax.ucd.ie>, wrote: % Are verbose comments appropriate? Verbose comments are % - tedious to read % - spoil the visual structure of the code % - are seldom updated by maintainence programmers and so aren't reliable % anyway! Of course, in a Literate program, the code interupts the visual structure of the comments. The question the comments should be answering is `what is this code trying to do?'. It isn't always clear, and sometimes you wonder why something was done the way it was done. I've spent a lot of time picking up other people's programs, and I very often want to ask them what they were trying to achieve with it. Short comments, or even short, terse comments, are not usually enlightening: x = 0; /* assign 0 to x */ is the classic example of a completely useless, but short, piece of documentation. % I always encourage students to write short, terse comments. Well-written % code is often self-explanatory and the complexity involved understanding % the larger system is better managed by studying the design documentation. Ah -- but there is no design documentation. In real world systems, written by professional programmers, design tends to be at a very high level, and there's nothing to describe the way some little piece of the puzzle has been put together. In a literate program, at least in theory, the design documentation is stored in the program source file. It's just as tedious to read there as it would be somewhere else, but it's right there, where it's handy if you're trying to figure out what the last SOB that touched this code was trying to do. Of course, the point I was trying to make before (I think I've edited it out of this response) was that by encouraging you to write a description of what you're trying to do (aka a verbose comment), LitProg encourages you to think about what you're trying to do, which is likely to reduce the need for maintenance in the future. So, I would argue the opposite to `plenty of terse comments' -- give me one cogent explanation of what you're trying to do, and I can read your code to see what you actually did do. There isn't much you can tell me in a terse comment that's likely to be of any help. -- Patrick TJ McPhee Toronto Canada ptjm@io.org ================================================================================ Archive-Date: Wed, 15 Feb 1995 17:22:16 CDT Sender: owner-litprog@SHSU.edu From: ceblackcat@aol.com (CeBlackCat) Subject: Qbasic program Date: 15 Feb 1995 18:03:09 -0500 Message-ID: <3hu17d$7re@newsbf02.news.aol.com> Reply-To: LitProg@SHSU.edu, ceblackcat@aol.com (CeBlackCat) To: LitProg@SHSU.EDU Hello, can anyone help me write a program that dials a number, logs wether it is data or voice and then dials the next number in the pattern. (similar to the program Matthew Broderick uses in the movie "WarGames') please e-mail any help you can give Thanks much, BlackCat ================================================================================ Archive-Date: Thu, 16 Feb 1995 00:30:44 CDT Sender: owner-litprog@SHSU.edu From: scherer@genesis.informatik.rwth-aachen.de (Andreas Scherer) Reply-To: LitProg@SHSU.edu, scherer@GENESIS.INFORMATIK.RWTH-AACHEN.DE Subject: CWEB and LaTeX Date: Wed, 15 Feb 1995 11:12:53 Message-ID: Keywords: CWEB, LaTeX, Literate Programming To: LitProg@SHSU.EDU Dear Literate Programmers, As the maintainer of CWEB 3.3 [p11a] in CTAN and AMINET I should know the answer to this, but in fact I don't, so please, could someone give me a helping hand. I have been asked about `CWEB and LaTeX' several times and would like to know the whereabouts of `cweb.sty' for either LaTeX 2.09 and/or LaTeX2e. Personally, I'm quite content with the `cwebmac' output for plainTeX produced by CWEAVE, but obviously there's demand for LaTeX support as well. Many thanks in advance, Andreas Scherer Aachen University of Technology, Germany ================================================================================ Archive-Date: Thu, 16 Feb 1995 00:59:13 CDT Sender: owner-litprog@SHSU.edu From: sfiresto@interserv.com Reply-To: LitProg@SHSU.edu, sfiresto@INTERSERV.COM Subject: SAVE TAX DOLLARS!!! Date: 16 Feb 1995 06:43:55 GMT Message-ID: <3hus7b$dam@moon.earthlink.net> To: LitProg@SHSU.EDU SAVE TAX DOLLARS!!! =================== Did you know that your PC, home office, and equipment may be tax deductible under current tax laws? This is true even if you use your PC in very limited business applications! Federal tax laws are often confusing and most tax preparation services do not understand the significant savings that your investment in office and computing equipment may qualify you for. Based on a legal brief by a prominent Los Angeles tax attorney for his celebrity clients, this is an easy-to- read, step-by-step guide to home office tax deductions. This write-up is written in plain English and covers all current tax law. It is an invaluable aid to legal tax deductions. Others have paid hundreds and even thousands of dollars for this expensive service. Now you can have this valuable money-saving information for only $7.95! With April 15 coming soon, you have no time to lose. If you pay U.S. taxes and use a portion of your home for business purposes, you need this write-up! E-mail for further information. ================================================================================ Archive-Date: Thu, 16 Feb 1995 08:32:28 CDT Sender: owner-litprog@SHSU.edu From: ravn@imada.ou.dk (Thorbjoern Ravn Andersen) Reply-To: LitProg@SHSU.edu, ravn@IMADA.OU.DK Subject: Re: Clueless questions about literate programming are welcome here Message-ID: <1995Feb16.111549.17987@imada.ou.dk> Date: Thu, 16 Feb 1995 11:15:49 GMT To: LitProg@SHSU.EDU In <1995Feb13.131606.57792@ccvax.ucd.ie> melocin@ccvax.ucd.ie writes: >I always encourage students to write short, terse comments. Well-written >code is often self-explanatory and the complexity involved understanding >the larger system is better managed by studying the design documentation. My major incentive for using a LitProg tool is the ability to *easily* plug in a descriptive graph of e.g. a datastructure. Pointer usage is *much* easier if you have the datastructure easily laid out by a good drawing (NOT ascii). Just because you have the opportunity to use a lot of words, don't mean that you *HAVE* to write a lot. >I'd agree with 'plenty of appropriate, terse' comments! Same here - I just want to have a choice. A good explanation of a complex datastructure is hard to put in comments around the code. This usually goes in a block of text anyway, so why not typeset it properly; then the terse comments relate to the full explanation. Besides, too many comments can make code hard to read, and maintain. Regards, -- Thorbjørn Ravn Andersen "...and...Tubular Bells!" ravn@imada.ou.dk ================================================================================ Archive-Date: Thu, 16 Feb 1995 08:42:16 CDT Sender: owner-litprog@SHSU.edu Subject: Re: Separate Compilation Message-ID: <1995Feb16.104848.24588@wisipc.weizmann.ac.il> From: oren@marganit.weizmann.ac.il (Ben-Kiki Oren) Reply-To: LitProg@SHSU.edu, oren@MARGANIT.WEIZMANN.AC.IL Date: Thu, 16 Feb 1995 10:48:48 GMT To: LitProg@SHSU.EDU Christopher Booth (cjmb@signal.dra.hmg.gb) wrote: > In article <1995Jan30.200706.26129@wisipc.weizmann.ac.il>, oren@hadar.weizmann.ac.il (Ben-Kiki Oren) writes: > >... > >So, is there some blessed soul who has already implemented such a scheme? > >If not, has literate programming ever been implemented for projects with > >a multitude of cross-referencing source files worked on by multiple > >programmers? How did they do it, then? Am I missing something obvious? > Seconded. I too have used noweb to write C++ in separate classes > like this, and you would gasp to see the kludgy way I have tried > to get around this problem. It does seem as though it should be > possible to address the issue of referencing other WEB documents > without physically including them at the level of WEB code (in > whatever dialect :-). I've implemented a patch to noweb-2.6c which supports external cross references between noweb files. I'm not going to post it, though, since Normal is working on adding similar functionality into the `official' noweb release. He is doing an orderly integration into the system, while my patch is a quick-and-dirty hack. He also takes a slightly different approach then mine, so you are better off waiting for him to finish. In case you really need it immediately, I'll be happy to send the patch by E-mail. The noweb files should be compatible with Norman's enhancement, or could become so using a trivial filter. Oren. -- Life is tough and the hard ships are many. ================================================================================ Archive-Date: Thu, 16 Feb 1995 10:55:09 CDT Sender: owner-litprog@SHSU.edu Subject: Fine Points of CWEB (Was: Spidery WEB for Perl?) Message-ID: <1995Feb15.081224.1915@rhodes> From: stuart@zen.mathcs.rhodes.edu (Brian L. Stuart) Reply-To: LitProg@SHSU.edu, stuart@ZEN.MATHCS.RHODES.EDU Date: 15 Feb 95 08:12:24 -0500 To: LitProg@SHSU.EDU In article , maavl@cwi.nl (Marc van Leeuwen) writes: |> Here you must be referring to CWEB or something derived from it, because IMO |> the real reason for this problem has nothing to do for WEB systems in |> general (e.g., it does not apply to Pascal WEB). Rather, it is caused by an |> error made in converting WEB to CWEB that was never corrected, namely a |> failure to recognise the fundamentally different roles of semicolons in |> Pascal and C. In Pascal semicolons separate statements, whether simple |> (e.g., assignments) or compound, so if any such statement is followed |> sequentially by another one, a semicolon is required after the first; the |> requirement still holds if the first statement is a refinement. In other |> words, in Pascal one has `refinement -> statement' always, without having to |> consider LINE_END, and without having to use `@;' (either a real semicolon |> is required after it, or nothing is, e.g., when ELSE follows). In C however, |> no symbol separates successive statements, but things like assignments are |> expressions rather that statements, and they only become statements by |> incorporating a following semicolon. Since refinements almost always stand |> for (compound) statements, they should be given that category; however in |> (Levy/Knuth) CWEB they are given the same category as assignments, which is |> `expression'. This forces one to write a semicolon after each refinement, |> even though that really becomes a spurious empty statement; if such an empty |> statement would mess up the real syntax (the compiler would fail) then one |> has to write `@;' instead. In CWEBx where the category of refinements is |> `statement', this problem simply does not exist, and you never write a |> semicolon after a refinement. Just to play devil's advocate and because I've use it this way a few times, how do you handle a case where a fragment is indeed meant to replace an expression rather than a group of statements? (@+ ?) For example (albeit contrived): for( ) { ... } where = p = head; p != NULL; p = p->next or the like. It seems to me that this can make such very common idioms very readable to the non-experienced such as students and professionals new to the language. It's also a good place to isolate and discuss assumptions regarding the list like whether or not sentinals are used and the like. Along those lines, if I have many such loops, I can reuse many times and if the assumptions of the list change, I only need to find and change this one fragment definition. Of course, I don't use fragments this way nearly as often as I do to replace statements so I would tend to agree that the default behavior should be based on the usage as statements. Brian L. Stuart Math/CS Dept, Rhodes College, Memphis, TN stuart@mathcs.rhodes.edu ================================================================================ Archive-Date: Thu, 16 Feb 1995 14:14:42 CDT Sender: owner-litprog@SHSU.edu From: ZEKI@ECL.PSU.EDU (Zeki Akcali) Reply-To: LitProg@SHSU.edu, ZEKI@ECL.PSU.EDU Subject: All possible combinations Date: 16 Feb 1995 20:08:24 GMT Message-ID: <3i0bbo$18s2@hearst.cac.psu.edu> To: LitProg@SHSU.EDU Hi guys, I immediately need your help. I need to find all possible combinations of "k" elements out of a group of "n" elements, where 0 <= k <= n. Say we have a group like {1,2,3,4,5} all the possible combinations out of this group with 3 elements are : (1,2,3) ; (1,2,4) ; (1,2,5) ; (1,3,4) ; (1,3,5) ; (1,4,5) ; (2,3,4) ; (2,3,5) ; (2,4,5) ; (3,4,5). The total number of combinations is 5! -------------- = 10 3! (5-3)! I need to write this program in C. I really appreciate it if you can help me. Thanking you in advance. Best regards, Zeki AKCALI ================================================================================ Archive-Date: Fri, 17 Feb 1995 04:14:43 CDT Sender: owner-litprog@SHSU.edu Date: Fri, 17 Feb 95 11:14:14 +0100 From: s6404kol@sun10.vsz.bme.hu (Kolma Kornel) Reply-To: LitProg@SHSU.edu, s6404kol@SUN10.VSZ.BME.HU Message-ID: <9502171014.AA26281@sun10.vsz.bme.hu> To: litprog@shsu.edu unsubscribe litprog kolma kornel ================================================================================ Archive-Date: Fri, 17 Feb 1995 06:48:11 CDT Sender: owner-litprog@SHSU.edu From: utcke@nerys.ti1.tu-harburg.de (Sven Utcke) Reply-To: LitProg@SHSU.edu, utcke@NERYS.TI1.TU-HARBURG.DE Subject: Re: I Want to LEARN! Date: 14 Feb 1995 15:00:58 GMT Message-ID: <3hqgja$ppm@rztsun.tu-harburg.de> To: LitProg@SHSU.EDU In article , irr000494@interramp.com writes: |> |> > >Hello! |> > > I'm totally new to programming (as if you didn't already |> > >guess) and I would like to learn some languages for IBM/DOS. I |> > >just want to start out with something basic. (excuse the pun) |> > > So If you have any Ebooks, guides, programs etc. that are |> > >sorta simple and you have the time to email 'em to me, it would |> > >be much appreciated! |> > |> > For the seventh time, this is an inappropriate topic. The |> > comp.programming.literate group is for the discussion of Literate |> > Programming---the art of producing a text-processor readable documentation |> > and compiler readable programming files from the same source file. |> |> Thanks for being a complete asshole. You should be happy that people are |> trying to get into programming. Instead of replying in civil manner, you |> had to first downgrade the individual. This type of abuse will |> not increase anyone's desire to programm, if other experienced programmers |> as jerks. |> |> A. Quinn Hi A. Don't you think you're overdoing it a bit? The original poster was blatantly ignoring netiquette by neither reading the FAQ nor following the group for more than about 5 seconds (after pressing catch up --- or so it seems) and all he got was a matter-of-fact reply telling him so --- and, if memory serves me right, even some pointers where to look for more information. Could have been a lot worse, I would have thought... This should really have been a private mail rather than a follow-up. However, I thought I would just let the person who was sending these "For the n-th time..." mails know that I found his (her? don't remember. Take "his" to be a generic pronoun) replies adequate, to the point and even helpful and that I would have had neither the time nor the patience to answer in such a conciliatory way. Keep the good work up :) Sven -- e-mail: utcke@tu-harburg.d400.de finger: utcke@kirk.ti1.tu-harburg.de WWW : http://bashir.ti1.tu-harburg.de/~utcke/utcke.html ================================================================================ Archive-Date: Fri, 17 Feb 1995 12:06:17 CDT Sender: owner-litprog@SHSU.edu From: tinkrkel@america.net (Kelly Caldwell) Reply-To: LitProg@SHSU.edu, tinkrkel@AMERICA.NET Subject: Favorite OOA/OOD tools - POLL Date: 17 Feb 1995 17:38:38 GMT Message-ID: <3i2muu$8g5@peach.america.net> To: LitProg@SHSU.EDU SUBJECT - OBJECT ORIENTED ANALYSIS and DEVELOPMENT I am putting together a report on available OOA/OOD tools, who uses them, how they like them, etc. When I am finished, I will post some of the stats on what I found (no names, just stats from questionaire) that is, if you are interested. This poll is NOT for marketing purposes...it is actually for a graduate report. If you have an automated tool that you feel especially fond of, OR if you do not use an automated tool, but use some other notable methodology OR you just have an opinoin on some of the following questions...please send me some feedback by answering the following questions (please answer as completely as you can): ** When you are finished, please E-mail it directly to me at tinkrkel@america.net ** .............................................................POLL....................... .......................................................................... 1. What OO language (Smalltalk, C++, Objective C, Eiffel, Obj Pascal, Modula, ETC.) do you primarily use? 2. What country do you reside or work in? (Optional -just puts the other information in perspective) 3. Do you use an automated OOA/OOD tool (Rational Rose, Cadre OO, etc.)? If so, a. Which one? b. How easy is it to use? c. Does it do everything you would like it to? d. Would you recommend it to others? e. What methodology does it use? 4. Do you use any "hand" methodologies? If so, a. Which one? b. Please provide a short description (ESPECIALLY, if it is your own) 5. Are you also required to do "functional" programming? If so, a. What language is this (primarily) in? b. If you use an automated CASE tool, which one do you use (or prefer)? c. Why are you using a "functional language"? (Not flame bait...Client requires, project requires, real time, etc.) 6. Do you do any Client/Server or Distributed Database work using OO approaches? If so, a. What platform do you primarily use? b. What Database application do you primarily use to develop the Client? (Access, Paradox, Informix, etc) * Does it support the OO paradigm? * Does it do what you would like it to do? * Would you recommend it to others? c. What Database application do you primarily use to develop the Server? * Does it support the OO paradigm? * Does it do what you would like it to do? * Would you recommend it to others? d. What Database application do you primarily use to develop a Distributed Database? * Does it support the OO paradigm? * Does it do what you would like it to do? * Would you recommend it to others? 7. If you had to choose a necessary "toolkit" for OO designers and programmers, what would you include? 8. Is there another automated OOA/OOD tool that you have heard about, but haven't tried yet? If so, a. What is it (Name, manufacturer)? b. What have you heard about it? 9. Is there another Database application that you have heard about, but haven't tried yet? If so, a. What is it (Name, manufacturer)? b. What have you heard about it? 10. General comments? (Optional) 11. Would you like the stats of this poll posted (no names)? ............................................................. END POLL..................................................................................... ================================================================================ Archive-Date: Fri, 17 Feb 1995 17:57:42 CDT Sender: owner-litprog@SHSU.edu From: mattlud@aol.com (MattLud) Subject: Qbasic and QuickBasic. Please Explain Date: 17 Feb 1995 18:36:23 -0500 Message-ID: <3i3btn$8in@newsbf02.news.aol.com> Reply-To: LitProg@SHSU.edu, mattlud@aol.com (MattLud) To: LitProg@SHSU.EDU all, I have a QuickBasic source code that I want to be able to execute and run thru Qbasic, but Qbasic tells me that QUickBasic has several more commands. How Do I get QuickBasic, and what is its status --is it a commercial thing? ================================================================================ Archive-Date: Fri, 17 Feb 1995 20:27:46 CDT Sender: owner-litprog@SHSU.edu From: kthurs@sapient.com (Kimball Thurston) Reply-To: LitProg@SHSU.edu, kthurs@SAPIENT.COM Subject: Q: thoughts on changing over to LitProg mid-stream Date: 18 Feb 1995 02:15:36 GMT Message-ID: <3i3l88$mfl@mhaal.inhouse.compuserve.com> MIME-Version: 1.0 To: LitProg@SHSU.EDU Hi all, I'm a bit of a newbie with this whole literate programming 'thang, but I have a (I think) straight forward request that isn't totally asinine... I would like to start/resume a thread on people's thoughts or experiences with changing a development project already in progress to use a literate programming system. We currently have several design documents (object models, screen docs of what a screen is supposed to do, etc.) for each module we are developing, and then there are the inline comments and documentation. Of course, my team is having problems keep the two synchronized. It seems as if transferring existing work over would be a nightmare, requiring a bit of overhead... My question is do people think that having the documentation contain the code is worth the time to switch over, or should I just wait until the next phase of the project, and start then? thanks, Kimball -- Kimball Thurston kthurs@sapient.com 74774.1543@compuserve.com One Memorial Drive Cambridge MA, 02142 ================================================================================ Archive-Date: Sat, 18 Feb 1995 10:05:49 CDT Sender: owner-litprog@SHSU.edu From: tsl1@cornell.edu (Timothy Larkin) Reply-To: LitProg@SHSU.edu, tsl1@CORNELL.EDU Subject: ANNOUCEMENT: macweave Date: Sat, 18 Feb 1995 11:01:15 -0500 Message-ID: To: LitProg@SHSU.EDU This message announces the posting to the archive of a CWEB weave application for the Macintosh. Macweave is a Macintosh drag and drop application that weaves CWEB files. I do not know the author, or the version, nor do I remember where I obtained it. All I know is that it works with CWEB 3.1. Since it is the only Mac weaver I know of, I think it should be on the archive. I tried compressing the application, but the resulting file was larger than the original. So ``macweave'' is the application itself; be sure to download in binary mode. -- cordially, timothy larkin tsl1@cornell.edu ``A man can't be a dictator and design women's underwear. One or the other, but not both.'' Bertie Wooster ================================================================================ Archive-Date: Sat, 18 Feb 1995 13:03:05 CDT Sender: owner-litprog@SHSU.edu From: kencham@cs.umn.edu (deepak r. kenchammana-hosekote) Reply-To: LitProg@SHSU.edu, kencham@CS.UMN.EDU Date: Sat, 18 Feb 1995 13:02:48 -0600 Message-ID: <199502181902.NAA23751@ulysses.cs.umn.edu> To: LitProg@SHSU.EDU Subject: Request for Slides on LitProg for talk. Hi, Six months back I found out about literate programming and since then have been a regular of fweb. I have been trying to "spread the word around" in my research group and have found about 10-15 people who are enthusiastic to hear/learn about it. As a result I have planned to give them a 1hr talk on literate programming and some of the freely available litprog tools. I was wondering if anyone of you had given similar talks. If so, then I was wondering if you would be willing to share your slides/viewgraphs. The talk is to be given in 10 days time. If you have slides and are willing to pass them to me please do so before then. Thanks! \d. -- "What's done cannot be undone!" - Macbeth V.1(pre-emacs) "What's done can be C-/-ed!" - Macbeth V.1(post-emacs) ================================================================================ Archive-Date: Sun, 19 Feb 1995 17:55:05 CDT Sender: owner-litprog@SHSU.edu From: gdr11@cl.cam.ac.uk (Gareth Rees) Reply-To: LitProg@SHSU.edu, gdr11@CL.CAM.AC.UK Subject: Which LitProg system? Date: 19 Feb 1995 23:53:16 GMT Message-ID: To: LitProg@SHSU.EDU I'm interested in a literate programming system satisfying the following requirements: Programming Languages: any, especially LISP, C and SML Target for documentation: Emacs Info, plain text (ASCII), HTML, and Postscript I'd like to have a single source for the documentation, and generate multiple targets from that source, including appropriate material for each target. TexInfo's ability to have separate material in the Info and TeX versions of a document seems perfect for this. From reading the FAQ, and experimenting with FunnelWeb, FWEB and Noweb, My best choice would appear to be to use Noweb, using TexInfo as my markup language, and to write my own TexInfo back end. Or does anyone out there already have a TexInfo back end for noweb? Or a better solution? -- Gareth Rees ================================================================================ Archive-Date: Mon, 20 Feb 1995 15:47:58 CDT Sender: owner-litprog@SHSU.edu From: nordmi00@ac.usfca.edu (Nordberg) Reply-To: LitProg@SHSU.edu, nordmi00@AC.USFCA.EDU Subject: Re: Qbasic and QuickBasic. Please Explain Date: 20 Feb 1995 21:33:51 GMT Message-ID: <3ib1rv$ndm@noc.usfca.edu> To: LitProg@SHSU.EDU MattLud (mattlud@aol.com) wrote: : all, : I have a QuickBasic source code that I want to be able to execute and : run thru Qbasic, but Qbasic tells me that QUickBasic has several more : commands. How Do I get QuickBasic, and what is its status --is it a : commercial thing? Yes it is commercial software available from Microsoft. Programmers Paradise sells it for around $79.00. QBasic is a subset of Quick Basic. Quick Basic has an actual compiler so you can create exe files that don't require the user to have either QBasic or Quick Basic on their machine. Michael USF ================================================================================ Archive-Date: Tue, 21 Feb 1995 01:57:18 CDT Sender: owner-litprog@SHSU.edu From: a209grai@cdf.toronto.edu (your name here) Reply-To: LitProg@SHSU.edu, a209grai@CDF.TORONTO.EDU Subject: is this a good style? Message-ID: Date: Sat, 18 Feb 1995 09:40:20 GMT To: LitProg@SHSU.EDU I have just started reading this newsgroup. Am I right in thinking this newsgroup is about making your code more understandable and maintainable by proper commenting (or documentation)? If that is what we are talking about here then it is a good style to write my program as comments that say what I want to do then fill in the space between the comments with the appropriate code? This is what I typically do now. I'll format the comments by cutting and pasting just as I would edit an essay or report. Once I feel the entire project is adequately described I start filling in the code that goes with each comment. Some comments will require entire functions or blocks of code where as the more cryptic lines will have a comment for each line of code. Any suggestions for improvement? -- Darrell Grainger: darrell_grainger@ckbbs.hookup.net or current address. ================================================================================ Archive-Date: Tue, 21 Feb 1995 10:05:32 CDT Sender: owner-litprog@SHSU.edu From: elemings@unix1.utm.edu (Eric Lemings) Reply-To: LitProg@SHSU.edu, elemings@UNIX1.UTM.EDU Subject: Alternative LP Systems Date: 21 Feb 1995 15:40:18 GMT Message-ID: <3id1h2$mnq@martha.utk.edu> To: LitProg@SHSU.EDU Are there any LP systems that support PDL? Document languages other than TeX? Postscript possibly? How about full blown, word processing, GUI interface systems? Or have LP systems not advanced to this point yet? Why not? I would think the first IDE to offer a LP system as part of the package would not only be a huge success but have a large impact on programming as well. Eric Lemings ================================================================================ Archive-Date: Tue, 21 Feb 1995 21:25:48 CDT Sender: owner-litprog@SHSU.edu Date: Tue, 21 Feb 1995 18:57:00 -0700 (PDT) From: "Stephen Boyan (510) 926-3291/fax 926-3604" Reply-To: LitProg@SHSU.edu, BOYANST@NCAL.KAIPERM.ORG Subject: Re: Clueless questions about literate programming are welcome To: LitProg@shsu.edu > verbose versus terse (commenting) FWIW, The text editor WYLBUR had these as mode commands. Hypotactic versus paratactic literate programming styles could be the subject of a thread in this symposium. Examples of literate programs that Faulkner might have written could be compared to ones by Hemingway. That's a nice thing about LP. One can write not just comments, but a whole book, or at least a short story, about the program. ;-) Stephen Boyan boyanst@ncal.kaiperm.org ================================================================================ Archive-Date: Tue, 21 Feb 1995 21:48:37 CDT Sender: owner-litprog@SHSU.edu Date: Wed, 22 Feb 1995 03:05:00 -0700 (PDT) From: "Stephen Boyan (510) 926-3291/fax 926-3604" Reply-To: LitProg@SHSU.edu, BOYANST@NCAL.KAIPERM.ORG Subject: Re: Announcing: "TrueTeX" now a registered trademark To: LitProg@shsu.edu TEX (middle E not displaced) stands for Text EXecutive processor, done by Honeywell. Knuth mentions it in Chapter 1 of The TeXbook, where he calls it an admirable work. --- Stephen Boyan boyanst@ncal.kaiperm.org ================================================================================ Archive-Date: Tue, 21 Feb 1995 22:13:17 CDT Sender: owner-litprog@SHSU.edu Date: Wed, 22 Feb 1995 03:11:00 -0700 (PDT) From: "Stephen Boyan (510) 926-3291/fax 926-3604" Reply-To: LitProg@SHSU.edu, BOYANST@NCAL.KAIPERM.ORG Subject: RE: is this a good style? To: LitProg@shsu.edu Your approach to writing the comments first is very LP. LP should offer you better tools for this. Another aspect of LP is the psychological. LP is a programming paradigm that combines the source for a compiler-readable and a human-readable (and maintainable) program in one file. Sections of the program can be introduced to the human reader in the psychologically optimal (as you, the author, see that) order; the preprocessor creating the compiler input will rearrange things into the correct programmatic order, but the order of the maintenance document will remain unchanged. This lets the program be created more like a book. Pure commenting would follow the order of the compiler source. IMO, this emphasis on the psychological aspects of the code is very much woven into the entire concept of LP. Pretty printing is partly a psychological thing, and is a major issue in LP. --- Stephen Boyan boyanst@ncal.kaiperm.org ================================================================================ Archive-Date: Wed, 22 Feb 1995 00:35:59 CDT Sender: owner-litprog@SHSU.edu From: melocin@ccvax.ucd.ie Reply-To: LitProg@SHSU.edu, melocin@CCVAX.UCD.IE Subject: Re: Comments (Was: Clueless.....) Message-ID: <1995Feb21.161441.57875@ccvax.ucd.ie> Date: 21 Feb 95 16:14:41 WET To: LitProg@SHSU.EDU In article <3hs69v$5e8@ionews.io.org>, ptjm@io.org (Patrick TJ McPhee) writes: > In article <1995Feb13.131606.57792@ccvax.ucd.ie>, > wrote: > % Are verbose comments appropriate? Verbose comments are > % - tedious to read > % - spoil the visual structure of the code > % - are seldom updated by maintainence programmers and so aren't reliable > % anyway! > > Of course, in a Literate program, the code interupts the visual structure > of the comments. Isn't this a damning remark about literate programming? The code, which is a precise statement of what is being done, takes second place to the informal description by the programmer of what they wanted to do. > The question the comments should be answering is `what > is this code trying to do?'. It isn't always clear, and sometimes you > wonder why something was done the way it was done. I've spent a lot > of time picking up other people's programs, and I very often want to > ask them what they were trying to achieve with it. Short comments, or > even short, terse comments, are not usually enlightening: > x = 0; /* assign 0 to x */ > is the classic example of a completely useless, but short, piece of > documentation. This a strawman if ever I saw one! Do we need to say that comments which give an informal description of the semantics of program constructs aren't useful? > > % I always encourage students to write short, terse comments. Well-written > % code is often self-explanatory and the complexity involved understanding > % the larger system is better managed by studying the design documentation. > > Ah -- but there is no design documentation. In real world systems, written > by professional programmers, design tends to be at a very high level, and > there's nothing to describe the way some little piece of the puzzle has been > put together. What are you getting at here? There's no design documentation so we need lots of comments? I completely agree with you that puzzling pieces of code must be commented to explain what's going on, but these descriptions should be terse and to-the-point, not verbose. As Meyers puts it, a reader with literary inclinations would rather read Henry James. > In a literate program, at least in theory, the design > documentation is stored in the program source file. It's just as tedious > to read there as it would be somewhere else, but it's right there, where > it's handy if you're trying to figure out what the last SOB that touched > this code was trying to do. Of course, the point I was trying to make > before (I think I've edited it out of this response) was that by encouraging > you to write a description of what you're trying to do (aka a verbose comment), > LitProg encourages you to think about what you're trying to do, which is > likely to reduce the need for maintenance in the future. I agree with the aim: you should of course think about what you do when you program. However, attempting to clarify what you're doing by verbose text is going about it the wrong way, IMO. > So, I would argue the opposite to `plenty of terse comments' -- give me > one cogent explanation of what you're trying to do, and I can read your > code to see what you actually did do. There isn't much you can tell > me in a terse comment that's likely to be of any help. > > -- > > Patrick TJ McPhee > Toronto Canada > ptjm@io.org Regards, Mel O Cinneide ================================================================================ Archive-Date: Wed, 22 Feb 1995 01:26:45 CDT Sender: owner-litprog@SHSU.edu From: ok@goanna.cs.rmit.edu.au (Richard A. O'Keefe) Reply-To: LitProg@SHSU.edu, ok@GOANNA.CS.RMIT.EDU.AU Subject: Re: HELP!! Need info Date: 22 Feb 1995 17:55:53 +1100 Message-ID: <3ien5p$ep0@goanna.cs.rmit.edu.au> To: LitProg@SHSU.EDU anwrtbeer@aol.com (ANWRtbeer) writes: >Hi. I'm trying to help a friend find a computer programming job. >However, I'm confused on many things. Evidently. > 1) What is Oracle? Is it Dos Based Oracle is a toaster control language. It is no longer in use because it only ran on the PC Jr, and because modern toasters use a different bus. > 2) What is RPG, C, and/or C++? Ask your family physician. Don't worry, they _can_ be cured. > 3) Where can I purchase C, C++, or Oracle...or any language. If you want a language, many large cities have a "Foreign Language Bookshop". There was a great slavic languages bookshop on El Camino in Palo Alto. They may be able to help you. > 4) What is the future outlook for computer programming? Bleak. The pesky things are getting too small to _see_, let alone program. In addition, human literacy in the English-speaking world is eroding at a truly frightening rate. I blame the English teachers. >I'd like any info that anyone can give me. There is a lot of good info in the FAQs. comp.lang.c, comp.lang.c++, comp.databases.oracle have tons of info that is completely irrelevant to your needs. For the humour impaired, :-) :-) :-) -- "The complex-type shall be a simple-type." ISO 10206:1991 (Extended Pascal) Richard A. O'Keefe; http://www.cs.rmit.edu.au/~ok; RMIT Comp.Sci. ================================================================================ Archive-Date: Wed, 22 Feb 1995 09:20:17 CDT Sender: owner-litprog@SHSU.edu From: tinggard@iesd.auc.dk (Carsten Tinggard Nielsen) Reply-To: LitProg@SHSU.edu, tinggard@IESD.AUC.DK Subject: Where is nuweb.el ? Date: 22 Feb 1995 12:12:20 GMT Message-ID: MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit To: LitProg@SHSU.EDU According to the FAQ there should be a nuweb.el at CTAN, but where exactly (path)? I've tried CTAN in UK under the nuweb source, macros etc. but haven't found the file. Thanks -- +-----------------------------------------------------------------------------+ + A little bit of syntactic sugar helps swallow the lambda-calculus (Landin) + +-----------------------------------------------------------------------------+ + Institute of Electronic Systems | / | E-mail : tinggard@iesd.auc.dk + + Aalborg University | ._//( | S-mail : Sct. Hansgade 7 + + Fredrik Bajersvej 7, E1-212 | / | \ | DK-9700 Broenderslev + + DK-9220 Aalborg Oe | A U | +45 98 82 32 11 + +-----------------------------------------------------------------------------+ ================================================================================ Archive-Date: Wed, 22 Feb 1995 15:23:50 CDT Sender: owner-litprog@SHSU.edu From: mauer@cursa.math.uiuc.edu (Andrew John Mauer) Reply-To: LitProg@SHSU.edu, mauer@CURSA.MATH.UIUC.EDU Subject: Re: Comments (Was: Clueless.....) Date: 22 Feb 1995 21:13:28 GMT Message-ID: To: LitProg@SHSU.EDU -------- >>>>> "melocin" == melocin writes: melocin> In article <3hs69v$5e8@ionews.io.org>, ptjm@io.org (Patrick TJ McPhee) writes: >> In article <1995Feb13.131606.57792@ccvax.ucd.ie>, >> wrote: >> % Are verbose comments appropriate? Verbose comments are >> % - tedious to read >> % - spoil the visual structure of the code >> % - are seldom updated by maintainence programmers and so aren't reliable >> % anyway! >> >> Of course, in a Literate program, the code interupts the visual structure >> of the comments. melocin> Isn't this a damning remark about literate programming? The melocin> code, which is a precise statement of what is being done, melocin> takes second place to the informal description by the melocin> programmer of what they wanted to do. I do not believe so. The process of realizing the (abstract) goals of your program can and do obscure a useful (usually high-level) understanding of what the goals are. It is true that the code is a precise statement of what is being done is true, but this focuses on the implementation rather than the design. Although the analogy has its flaws, I think this is similar to saying that assembly code provides a more precise description than a C++ program... (you might get confused because it might not be obvious which virtual function was being called, for instance). I think that one of the tenants of literate programming is that understanding the existing code (in order to change it) is the most difficult part of the maintenance process. To understand the module that you are changing, you will want the high-level description of most parts (so you can skip over them because you know they are irrelevant), and only read the code in a small section. [...] melocin> I completely agree with you that puzzling pieces of code melocin> must be commented to explain what's going on, but these descriptions melocin> should be terse and to-the-point, not verbose. As Meyers puts melocin> it, a reader with literary inclinations would rather read melocin> Henry James. For me, literate programming makes the documentation/comments reflect the higher level structure, rather than the immediacy of (x=0). Most maintenance needs just a high level understanding of most program parts. /Andrew/ ================================================================================ Archive-Date: Wed, 22 Feb 1995 17:33:14 CDT Sender: owner-litprog@SHSU.edu From: simmons@krang.vis.mu.OZ.AU (Stephen Edward Simmons) Reply-To: LitProg@SHSU.edu, simmons@KRANG.VIS.MU.OZ.AU Subject: Current status of NUWEB? Message-ID: <9505410.3366@mulga.cs.mu.OZ.AU> Date: Wed, 22 Feb 1995 23:24:40 GMT To: LitProg@SHSU.EDU Hello, My first foray into Literate Programming was to obtain NUWEB 0.87b and port it to a PC. While reading the manual for NUWEB, I decided that there was one aspect of it that I would like to change. In particular, the LaTeX formatting for the WEB source code is rigidly defined in NUWEB's source code. This means that there is no simple way of redefining the visual appearance of NUWEB's LaTeX output without altering the source code and redefining. (to change, for example, 'scrap' to 'section' and use something other than a diamond to mark the end of each section.) To my mind, it would be more in keeping with the general philosophy of LaTeX (and especially LaTeX2e) if the NUWEB source code just enclosed the WEB file's source code in an environment, and a header file such as NUWEB.STY could be used to change the visual appearance of the LaTeXed output without having to recompile NUWEB. What is the current status of NUWEB? Is Preston Briggs or anyone else developing NUWEB further? Do people who have had more experience with literate programming than me (i.e. more than none!) feel that this would be sensible/worthwhile? Thanks, Stephen Simmons simmons@ee.mu.oz.au ================================================================================ Archive-Date: Thu, 23 Feb 1995 00:17:54 CDT Sender: owner-litprog@SHSU.edu From: karen@chemeng.uct.ac.za Reply-To: LitProg@SHSU.edu, karen@CHEMENG.UCT.AC.ZA Subject: ANSI curses.h C header file for DOS Date: Thu, 23 Feb 1995 06:00:37 GMT Message-ID: To: LitProg@SHSU.EDU Hello I am trying to port a UNIX gnu c program to DOS, this requires the standard curses.h library file, the file which I have accompanies UNIX gnu c. Does anyone know of a DOS equivalent, or does anyone have some advice or suggestions etc. for me. All replies welcome. Thanks Karen ---------------------------------------------------------------------- +--****** Get-A-Way gang on the Argus ******--+ ---------------------------------------------------------------------- __~@ __~@ __~@ Ride ----- __~@ _-\__<,_-\__<, _-\__<, for your life... ----- _-\__<, (*)/' ((*)/' (*) (*)/' (*) ----- (*)/' (*) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Trev Paul Kahlie Megs (off to Durbs) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Karen van der Linde karen@chemeng.uct.ac.za University of Cape Town Chemical Engineering Department ================================================================================ Archive-Date: Thu, 23 Feb 1995 02:50:29 CDT Sender: owner-litprog@SHSU.edu From: stw113@psu.edu (Sean Werkema) Reply-To: LitProg@SHSU.edu, stw113@PSU.EDU Subject: Re: ANSI curses.h C header file for DOS Date: Thu, 23 Feb 1995 08:11:19 GMT Message-ID: To: LitProg@SHSU.EDU >Hello >I am trying to port a UNIX gnu c program to DOS, this requires the standard >curses.h library file, the file which I have accompanies UNIX gnu c. >Does anyone know of a DOS equivalent, or does anyone have some advice or >suggestions etc. for me. >All replies welcome. >Thanks >Karen A few days ago I downloaded DJGPP from SimTel via oak.oakland.edu. It took a little work to set up, but it did fulfill its promise: It's a fully functional GNU C and C++ port to DOS systems. I haven't had a chance to do much with it yet, but I did notice that it had curses.h in it. Might want to try it, but it will eat up a fair chunk of hard disk space (about 20 Megs on my system). It's a rather nice compiler, I think. -------------------------------------------------------------------- Standard Disclaimer: I didn't say any of Rules for precision: what you thought I didn't think I said. Measure with micrometer. stw113@psu.edu (Sean Werkema) Mark with chalk. BCNU :) Cut with axe. ================================================================================ Archive-Date: Thu, 23 Feb 1995 04:58:41 CDT Sender: owner-litprog@SHSU.edu From: Carsten Tinggard Nielsen Reply-To: LitProg@SHSU.edu, tinggard@IESD.AUC.DK Date: Thu, 23 Feb 1995 11:57:55 +0100 Message-ID: <199502231057.LAA08755@iota.iesd.auc.dk> To: ddw@miscrit.be CC: LitProg@SHSU.edu Subject: Re: Where is nuweb.el ? Thanks for the pointer, I found the file. Regards, Carsten -- +-----------------------------------------------------------------------------+ + Institute of Electronic Systems | / | E-mail : tinggard@iesd.auc.dk + + Aalborg University | ._//( | S-mail : Sct. Hansgade 7 + + Fredrik Bajersvej 7, E1-212 | / | \ | DK-9700 Broenderslev + + DK-9220 Aalborg Oe | A U | +45 98 82 32 11 + +-----------------------------------------------------------------------------+ ================================================================================ Archive-Date: Thu, 23 Feb 1995 07:12:47 CDT Sender: owner-litprog@SHSU.edu Date: Thu, 23 Feb 95 11:05:36 +0100 From: ddw@miscrit.be (Dominique de Waleffe) Reply-To: LitProg@SHSU.edu, ddw@MISCRIT.BE Message-ID: <9502231005.AA10411@miscrit.be> To: LitProg@SHSU.edu, tinggard@IESD.AUC.DK Subject: Where is nuweb.el ? References: >>> "Carsten" == Carsten Tinggard Nielsen writes: Carsten> According to the FAQ there should be a nuweb.el at CTAN, but where Carsten> exactly (path)? I've tried CTAN in UK under the nuweb source, macros Carsten> etc. but haven't found the file. The source of nuweb.el are in the elisp-archives in modes/nuweb.el.Z or .gz They once were on CTAN. Regards, D. -- Dominique de Waleffe Mission Critical, Wijnegemhofstraat 199, B-3071 Erps-Kwerps (Belgium) Phone: +32 2 759 95 60 Fax: +32 2 759 27 60 email: ddw@acm.org, ddw@miscrit.be PGP key fingerprint: F9 CC 23 74 44 62 7C F3 8C 12 DF 71 BB 60 54 98 ================================================================================ Archive-Date: Thu, 23 Feb 1995 09:50:24 CDT Sender: owner-litprog@SHSU.edu From: akp3075@hertz.njit.edu (AMIT PAREKH) Reply-To: LitProg@SHSU.edu, akp3075@HERTZ.NJIT.EDU Subject: Cholesky's Factorization Message-ID: <1995Feb17.140033.18350@njitgw.njit.edu> Date: Thu, 23 Feb 1995 15:35:01 GMT To: LitProg@SHSU.EDU Hi friends, I am not sure if I am posting this in the right place....but here it is. I am looking for an algorithm or an implementation (possibly in C) for the Cholesky's Factorization for solving matrices...I am supposed to write a parallel implementation of this to be executed on the AP1000 and am not quite sure of the method to be used. Any help in this regard is highly appreciated... Please email the comments to akp3075@hertz.njit.edu because I am not a very regular user of news.... Thanks in advance Amit Parekh ================================================================================ Archive-Date: Thu, 23 Feb 1995 13:08:29 CDT Sender: owner-litprog@SHSU.edu Date: Wed, 22 Feb 1995 03:22:00 -0700 (PDT) From: "Stephen Boyan (510) 926-3291/fax 926-3604" Reply-To: LitProg@SHSU.edu, BOYANST@NCAL.KAIPERM.ORG Subject: RE: Alternative LP Systems To: LitProg@shsu.edu There is a WinWordWeb, developed by Lee Wittenberg. See the LP FAQ. When all else fails, try noweb. Many would advise also trying it before trying anything else. ================================================================================ Archive-Date: Thu, 23 Feb 1995 16:07:25 CDT Sender: owner-litprog@SHSU.edu Message-ID: <199502232206.JAA06109@hestia.ccs.deakin.edu.au> To: LitProg@SHSU.edu, karen@chemeng.uct.ac.za Subject: Re: ANSI curses.h C header file for DOS MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Date: Fri, 24 Feb 1995 09:06:33 +1100 From: Peter Horan Reply-To: LitProg@SHSU.edu, peter@DEAKIN.EDU.AU > Hello > > I am trying to port a UNIX gnu c program to DOS, this requires the standard > curses.h library file, the file which I have accompanies UNIX gnu c. > Does anyone know of a DOS equivalent, or does anyone have some advice or > suggestions etc. for me. > Use pdcurses. This is the current README at ftp.gu.edu.au: griffin.itc.gu.edu.au:/src/PDCurses ncftp>get README - This directory contains PDCurses, a public domain implementation of System V Curses. The following files are present: pdcurs22.zip - PDCurses 2.2 source code (latest release) dosbcc22.zip - compiled libraries for DOS Borland C++ 3.0 dosmsc22.zip - compiled libraries for DOS Microsoft C 6.0 dosdjg22.zip - compiled libraries for DOS DJGPP 1.12 os2icc22.zip - compiled libraries for OS/2 IBM C/Set2 os2emx22.zip - compiled libraries for OS/2 emx 0.09a dmake38-source.zip - source for dmake version 3.8 dmake38-dos-exe.zip - DOS executable for dmake 3.8 dmake38-os2-exe.zip - OS/2 executable for dmake 3.8 You may find a copy at a closer site. Peter Horan School of Computing and Mathematics peter@deakin.edu.au Deakin University Geelong +61-52-27 1234 (Voice) Victoria 3217 +61-52-27 2028 (FAX) Australia ================================================================================ Archive-Date: Thu, 23 Feb 1995 20:18:02 CDT Sender: owner-litprog@SHSU.edu From: ptjm@io.org (Patrick TJ McPhee) Reply-To: LitProg@SHSU.edu, ptjm@IO.ORG Subject: Re: Comments (Was: Clueless.....) Date: 23 Feb 1995 01:00:17 -0500 Message-ID: <3ih89h$pr0@ionews.io.org> To: LitProg@SHSU.EDU In article <1995Feb21.161441.57875@ccvax.ucd.ie>, wrote: % In article <3hs69v$5e8@ionews.io.org>, ptjm@io.org (Patrick TJ McPhee) writes: % > In article <1995Feb13.131606.57792@ccvax.ucd.ie>, % > wrote: % > % Are verbose comments appropriate? Verbose comments are % > % [..] % > Of course, in a Literate program, the code interupts the visual structure % > of the comments. % % Isn't this a damning remark about literate programming? It could be. It is, however, and in my opinion, the essence of Literate Programming. % The code, which is % a precise statement of what is being done, takes second place to the % informal description by the programmer of what they wanted to do. The code doesn't work. The code is a precise statement of how to do the wrong thing. But why? What's wrong? We can look at the design docs, and they'll tell us what this piece of code is supposed to do. This is how we know it doesn't work -- it doesn't do what the design docs say it's supposed to do. The problem is that the original programmer wasn't very good at his job, and he's been fired. It's not obvious from his code what approach he was taking to the problem, and it's not easy to see what's gone wrong if you don't know what he was trying to do. Sometimes there's no choice but to start over, because it's difficult to see how the different pieces of the code fit together. The problem with this argument is that a really useless programmer is not very likely to write a coherent explanation of what he's doing, anyway. On the other hand, if you force this bad programmer to write a description of the operation of each piece of code he writes, you may get him to recognise that some pieces are convoluted messes which should be rewritten before someone gets hurt. I suggest that this big picture effect won't be introduced by localised comments (which we've been calling terse), since such comments usually take into account only a few instructions of code. % > Short comments, or even short, terse comments, are not usually % > enlightening: % > x = 0; /* assign 0 to x */ % > is the classic example of a completely useless, but short, piece of % > documentation. % % This a strawman if ever I saw one! No, it's an extreme example. My assertion is that it's difficult to say the sorts of things I like to see in comments in only a few words, and I'm not usually interested in the programmer's opinion of things at an extremely localised level. I've seen things like this: x = 0; /* the x factor has to be reset */ and you have to be in tune with what's going on to understand this. Why does it have to be reset? What is the x factor anyway? Just the statement in the code gets me asking those questions, and the comment doesn't do anything for me. If it's really difficult to understand why x is being reset at this point, I would personally rather see something like this: `About half way through we reset |x| because Lipmann ({\it The X Factor in Programming}, pp 27--43) says it would be a terrible disaster if we didn't.' [ok -- I wouldn't rather see that, it's a parody going the other way. I'd like to see obscure things put into perspective]. % > % [if you want the big picture, look in the design docs] % > [but there are no design docs] % What are you getting at here? There's no design documentation so we need % lots of comments? There are no design docs at a level that helps in maintianing code, so your code should contain enough information to fill this void. Again, this seems to me to be the point of literate programming -- the proper place for a description of how a program should work is in the source code of the program. % I completely agree with you that puzzling pieces of code % must be commented to explain what's going on, but these descriptions % should be terse and to-the-point, not verbose. Certainly to the point. Almost never terse. $terse \to cryptic$. (That's terse approaches cryptic). Plus, I want to know about the code that was left out. I like comments that say `I didn't use because '. I don't have a big problem with comments that say `I used this bad approach because the good approach would take too long, and I've too much else to do.' At least you know where you stand. % As Meyers puts it, a reader with literary inclinations would rather read % Henry James. But someone who wants to maintain a piece of software wants to know what the original programmers were trying to do. Take care. -- Patrick TJ McPhee Toronto Canada ptjm@io.org ================================================================================ Archive-Date: Sun, 26 Feb 1995 19:06:48 CDT Sender: owner-litprog@SHSU.edu From: inform Reply-To: LitProg@SHSU.edu, iinform@POPHOST.EUNET.BE Subject: software for production planning Date: 26 Feb 1995 08:24:32 GMT Message-ID: <3ipds0$26r@news.Belgium.EU.net> To: LitProg@SHSU.EDU Hi, I'm looking for studies who evaluate different software packages for production planning. Does anyone know who has already made such a study ? Thanks for your help. Katia Waegemans ================================================================================ Archive-Date: Sun, 26 Feb 1995 19:08:35 CDT Sender: owner-litprog@SHSU.edu From: theedge@rbg.informatik.th-darmstadt.de (felix gaertner) Reply-To: LitProg@SHSU.edu, theedge@RBG.INFORMATIK.TH-DARMSTADT.DE Subject: Re: Comments (Was: Clueless.....) Date: 24 Feb 1995 08:07:36 GMT Message-ID: <3ik448$li1@rs18.hrz.th-darmstadt.de> To: LitProg@SHSU.EDU In article , mauer@cursa.math.uiuc.edu (Andrew John Mauer) writes: > It is true that the code is a precise statement of what is being > done is true, but this focuses on the implementation rather than the > design. Although the analogy has its flaws, I think this is similar to > saying that assembly code provides a more precise description than a > C++ program... (you might get confused because it might not be obvious > which virtual function was being called, for instance). The code is a precise statement of what is being done, sure enough. But is this also the thing that the programmer intended? I think it is one of the benefits of the LitProg paradigm that you are encouraged to first say (informally) in prose what you _want_ to do, and then express (formally) what is done. This just as an aside. Felix ================================================================================ Archive-Date: Sun, 26 Feb 1995 19:27:33 CDT Sender: owner-litprog@SHSU.edu From: sp106@york.ac.uk ("stephen") Reply-To: LitProg@SHSU.edu, sp106@YORK.AC.UK Subject: Re: Favorite OOA/OOD tools - POLL Date: 27 Feb 1995 00:38:59 GMT Message-ID: <3ir6v3$9e7@castle.york.ac.uk> To: LitProg@SHSU.EDU Kelly Caldwell (tinkrkel@america.net) wrote: : I am putting together a report on available OOA/OOD tools, who uses them, : how they like them, etc. When I am finished, I will post some of the stats on what I : found : [etc etc] I have a favourite tool that is hardly OO based, it's called fmt(1) and it stops me sending messages with lines over 72 characters long. You may find it useful. #################################################### # sp106@york.ac.uk # http://www.york.ac.uk/~sp106 # # Each set includes a turntable, nine inch icing # # bag, six high definition nozzles... # #################################################### ================================================================================ Archive-Date: Sun, 26 Feb 1995 19:30:31 CDT Sender: owner-litprog@SHSU.edu From: jhubbard@earthlink.net Reply-To: LitProg@SHSU.edu, jhubbard@EARTHLINK.NET Subject: Business on the Internet Date: 25 Feb 1995 05:01:47 GMT Message-ID: <3imdjs$1di@mars.earthlink.net> To: LitProg@SHSU.EDU Business Opportunity on the Internet......................... I have recently started a consulting company that provides Internet ad services to small to medium sized businesses. Specifically I am working with companies that are not as "computer literate" as larger companies but have a product that would benefit from having a www home page. I have contacted several target companies and have seen quite a bit of interest. I have a good knowledge of PC computing and use of Windows. I also have the organizational and management aspects of this venture well thought out. I am looking for an individual that is experienced in HTML document creation to provide me with the necessary webb page creation and programming support. I am also interested in finding out what it would require, both in hardware and software, to become a node on the Internet who actually could provide the service of becoming a site where clients could house their webb sites. I am a college graduate, with only one class to complete with my Engineering Management Masters Degree. I work full time with a top consulting company and can handle the consulting and management aspects of the business. I am looking for an individual(s) that would be interested in working on a consulting basis to help with the technical and programming aspect of this venture. For logistics purposes the candidate(s) must reside in the southern California area. EMail serious inquiries only to the address listed below. Thanks For Your Consideration Jim Hubbard jhubbard@earthlink.net InterAd (Internet Advertising) ================================================================================ Archive-Date: Sun, 26 Feb 1995 19:32:07 CDT Sender: owner-litprog@SHSU.edu From: blitherakt@aol.com (Blitherakt) Subject: Hello! Date: 26 Feb 1995 03:54:34 -0500 Message-ID: <3ipfka$ja9@newsbf02.news.aol.com> Reply-To: LitProg@SHSU.edu, blitherakt@aol.com (Blitherakt) To: LitProg@SHSU.EDU I've just started my subscription to this news group. SO!!! First of all, Hello! Now, down to business: A friend and I are looking for some people with IBM PC systems and C/C++,Assembly, or just about anything else that is manageble (preferably not Simula, Forth, Lisp and the like) programming experience for an interesting (at least we think it is) venture. We would like to get a group (a "Think Tank", if you will) of programmers together to author some utilities and/or games via the Internet. The way this would operate is this: A detailed application description/specification form would be drawn up and distributed to the members who would pick and choose the portions they would like to work on. On a regular basis, code will be sent to Me and my associate for Compilation, merging, and bug reporting. Eventually, something that works should evolve! We would maintain a Database of all programmers, their addresses (Internet, home or whatever you wish), and the total contribution in meaningful lines of code (i.e. 19,999 line comment blocks will be excluded). When (or should I say, IF) the programming project is released, everyone who made contributions to the project will be mentioned in the code and will be paid based on that contribution. We haven't worked out the method of payment yet (whether it will be like a quarterly royalty or a lump sum payment) as we're trying to get a feel for the interest in this kind of venture. We also feel that it would be ideal for the "Weekend Warrior" type of programmer; one who programs on a piecemeal basis for enjoyment of programming. If this sounds good to you, or you just have some general comments or suggestions, please send them to: Blitherakt@aol.com Looking forward to hearing from you! Tim Adamec aka Blitherakt ================================================================================ Archive-Date: Sun, 26 Feb 1995 19:34:33 CDT Sender: owner-litprog@SHSU.edu From: weiqigao@crl.com (Weiqi Gao) Reply-To: LitProg@SHSU.edu, weiqigao@CRL.COM Subject: Re: Business on the Internet Date: 25 Feb 1995 06:57:42 GMT Message-ID: <3imkd6$ord@nntp.crl.com> MIME-Version: 1.0 To: LitProg@SHSU.EDU In article <3imdjs$1di@mars.earthlink.net>, jhubbard@earthlink.net says... > >Business Opportunity on the Internet......................... > > > I have recently started a consulting company that provides Internet ad services to small to medium sized businesses. Specifically I am working wi >companies that are not as "computer literate" as larger companies but have a product that would benefit from having a www home page. I have contacted sev >target companies and have seen quite a bit of interest. > > I have a good knowledge of PC computing and use of Windows. I also have the organizational and management aspects of this venture well thought ou >am looking for an individual that is experienced in HTML document creation to provide me with the necessary webb page creation and programming support. > > I am also interested in finding out what it would require, both in hardware and software, to become a node on the Internet who actually could prov >service of becoming a site where clients could house their webb sites. > > I am a college graduate, with only one class to complete with my Engineering Management Masters Degree. I work full time with a top consulting co >and can handle the consulting and management aspects of the business. > > I am looking for an individual(s) that would be interested in working on a consulting basis to help with the technical and programming aspect of t >For logistics purposes the candidate(s) must reside in the southern California area. > > EMail serious inquiries only to the address listed below. > >Thanks For Your Consideration > >Jim Hubbard >jhubbard@earthlink.net >InterAd (Internet Advertising) > > For the tenth time, this topic is inappropriate for this group. This group is dedicated to discussions of Literate Programming issues---mostly for programmers who thinks they are writting a novel when they write a program. The Internet Advertising through WWW pages is interesting, though. To bad I'm not in S.Cal. 'cuz I could have set you up as an internet node in no time. :) If only you have a client! Weiqi Gao weiqigao@crl.com ================================================================================ Archive-Date: Sun, 26 Feb 1995 20:12:11 CDT Sender: owner-litprog@SHSU.edu From: Roger Helmendach Reply-To: LitProg@SHSU.edu, rhelmendach@ESRI.COM Subject: JOB AVAILABLE Date: 24 Feb 1995 20:03:33 GMT Message-ID: <3ile2l$141@esri.com> To: LitProg@SHSU.EDU JOB POSITION: CGM / Plotting Systems Engineer We are looking for a person to fill a permanent, full time position with ESRI, a very stable, large company. I am not a head hunter, but an employee of ESRI. If you feel you meet all the qualifications below and are interested, please email me with a brief explanation of your qualifications and how you may be contacted: Send email to: rhelmendach@esri.com Please respond ONLY IF YOU QUALIFY based on the following: - Have indepth knowledge of the CGM graphics format (2 years experience). - Any experience working with existing CGM I/O packages a plus. - Know how to program in 'C' (2 years experience). - Have experience writing plotter drivers (give formats your familiar with). - Don't mind maintaining an existing base of drivers. - Feel you work well with others in a team environment. - Would be willing to relocate to the southern California area. The position would involve taking on and maintaining existing plotter drivers as well as becoming the resident CGM guru for input and output. We already have I/O for CGM, but would like a tighter integration. ================================================================================ Archive-Date: Sun, 26 Feb 1995 21:41:19 CDT Sender: owner-litprog@SHSU.edu Date: Sat, 25 Feb 1995 02:10:00 -0700 (PDT) From: "Stephen Boyan (510) 926-3291/fax 926-3604" Reply-To: LitProg@SHSU.edu, BOYANST@NCAL.KAIPERM.ORG Subject: Re: Comments (Was: Clueless.....) To: LitProg@shsu.edu > the programmer wasn't very good at his job, and he's been fired More likely, he's been promoted to management. For further enhancements of this idea, see any reasonable sample of Dilbert's. In one I saw recently, it was explained that management is nature's way of removing negative contributors from the productive stream. ================================================================================ Archive-Date: Sun, 26 Feb 1995 23:12:12 CDT Sender: owner-litprog@SHSU.edu From: neodem@aol.com (NeoDem) Subject: Wanted : Windows programmers Date: 26 Feb 1995 23:59:54 -0500 Message-ID: <3irm8a$46b@newsbf02.news.aol.com> Reply-To: LitProg@SHSU.edu, neodem@aol.com (NeoDem) To: LitProg@SHSU.EDU Hello, pardon my intrusion on this newsgroup. I'm posting this message on this and a few other newgroups in search of helpers in the creation of a new type of communication software. I'm an independent computer consultant specializing in the installation of desk top publising systems. Recently, one of my clients was discussing with me a problem that he had. What came out of the conversation was an idea for a new type of software that could solve his, and probably many others, problem. The idea, although not in my field, was a very good one and he and I decided to try and create an application that could address the problem he had. His involvement was that he would support my research and, hopefully, finance the marketing of the application, if it ever got completed. My involvement, of course, was to create the application itself. So, in my spare time, I've been working on this project. The first step was to decide on the platform. Even though I'm very familiar with the Macintosh, I decided instead to create the application in the Windows envirinment. Simply because of the number of Windows platforms around, and also the large munber of Windows programmers around. Because I'm not very well versed in Windows programming, I've naturally got a few questions. Since the application will also utilize the internet, specificly ftp and e-mail, I will need some help there because I'm a bit of a novice in that area as well . So, I was wondering if there were any programmers or internet junkies that could answer some of my questions for me via e-mail. It's possible that I may also sub-contract out some of the programming if the need arises. Some of the specific areas of expertese that I'm looking for include: automated internet file transfer via Windows, automated ftp site searching, and automated e-mail retrieval. If you feel that you are an expert in any or all of these areas, please contact me. I think that this application will sell very well and anyone involved in its creation will be not only rewarded financially, but will probably be considered a pioneer in the next generation of internet computing. Thanks for your consideration and I'll be anxiously awaiting your replies!! ================================================================================ Archive-Date: Mon, 27 Feb 1995 00:13:03 CDT Sender: owner-litprog@SHSU.edu From: norman@flaubert.bellcore.com (Norman Ramsey) Reply-To: LitProg@SHSU.edu, norman@FLAUBERT.BELLCORE.COM Subject: Noweb v2.8 supports nuweb, converts latex to HTML Message-ID: Date: Sat, 25 Feb 1995 14:54:19 GMT To: LitProg@SHSU.EDU I am pleased to announce the release of version 2.8 of noweb. I've bumped the version number because of the addition of two features: - Noweb now sports an efficient, one-pass LaTeX to HTML converter. The converter is distributed in two forms: `l2h' acts as a noweb filter, converting only documentation chunks, and `sl2h' can be used on complete latex documents. You can think of `l2h' as an `anti-latex2html'; it is fast, extensible, has no options, and uses no bitmaps. - Noweb can now deal with nuweb programs; from the nuweb source code I have hacked up a parser that reads nuweb format and emits noweb pipeline format. When combined with l2h, this parser makes it possible to create HTML documents from existing nuweb files that contain latex markup. You get to click on an identifier and jump to the chunk (scrap?) containing its definition. For example, on the noweb home page you can find a pointer to the file created by the following command: noweave -markup numarkup -filter l2h -html -index nuweb.w > nuweb.html The noweb home page is located at: ftp://bellcore.com/pub/norman/www/noweb/intro.html The other notable change in version 2.8 is that I have re-arranged the directory structure as follows: binaries Pre-built distributions containing binaries and documentation contrib software contributed by noweb users examples sample noweb filters and programs in different languages src Source code and documentation (including FAQ) for noweb Unless you want everything, you will probably want to fetch src.tar.gz (and possibly contrib and examples) rather than the whole thing. So far I'm distributing linux and (old) DOS binaries. The advantage of these distributions is you can get the benefits of the Icon versions of the noweb filters without having to install Icon. Finally, version 2.8 contains some bug fixes and a number of small improvements in the HTML support. Noweb is available from CTAN (ftp.shsu.edu, ftp.tex.ac.uk, and ftp.uni-stuttgart.de) in directory /tex-archive/web/noweb. Norman Ramsey -- Norman Ramsey norman@bellcore.com ================================================================================ Archive-Date: Mon, 27 Feb 1995 04:25:48 CDT Sender: owner-litprog@SHSU.edu From: "Denis B. Roegel" Reply-To: LitProg@SHSU.edu, Denis.Roegel@LORIA.FR Date: Mon, 27 Feb 1995 11:25:54 +0100 Message-ID: <199502271025.LAA12099@pandore.loria.fr> To: LitProg@SHSU.edu Subject: what's going on ? CC: roegel@lorraine.loria.fr What has happened ? Is this list dead ? Almost nobody is subscribing now. It seems that I and a lot more people have been unsubscribed automatically around X-mas. Is that true ? Denis ================================================================================ Archive-Date: Mon, 27 Feb 1995 17:25:41 CDT Sender: owner-litprog@SHSU.edu From: norman@flaubert.bellcore.com (Norman Ramsey) Reply-To: LitProg@SHSU.edu, norman@FLAUBERT.BELLCORE.COM Subject: OOPS! The current version of noweb is 2.7, not 2.8 Message-ID: Date: Mon, 27 Feb 1995 22:00:17 GMT To: LitProg@SHSU.EDU My brain slipped a gear and I announced a nonexistent release of noweb. The current version (1 week old) is version 2.7, not version 2.8. I've cancelled the original announcement; here's a replacement... I am pleased to announce the release of version 2.7 of noweb. I've bumped the version number because of the addition of two features: - Noweb now sports an efficient, one-pass LaTeX to HTML converter. The converter is distributed in two forms: `l2h' acts as a noweb filter, converting only documentation chunks, and `sl2h' can be used on complete latex documents. You can think of `l2h' as an `anti-latex2html'; it is fast, extensible, has no options, and uses no bitmaps. - Noweb can now deal with nuweb programs; from the nuweb source code I have hacked up a parser that reads nuweb format and emits noweb pipeline format. When combined with l2h, this parser makes it possible to create HTML documents from existing nuweb files that contain latex markup. You get to click on an identifier and jump to the chunk (scrap?) containing its definition. For example, on the noweb home page you can find a pointer to the file created by the following command: noweave -markup numarkup -filter l2h -html -index nuweb.w > nuweb.html The noweb home page is located at: ftp://bellcore.com/pub/norman/www/noweb/intro.html The other notable change in version 2.7 is that I have re-arranged the directory structure as follows: binaries Pre-built distributions containing binaries and documentation contrib software contributed by noweb users examples sample noweb filters and programs in different languages src Source code and documentation (including FAQ) for noweb Unless you want everything, you will probably want to fetch src.tar.gz (and possibly contrib and examples) rather than the whole thing. So far I'm distributing linux and (old) DOS binaries. The advantage of these distributions is you can get the benefits of the Icon versions of the noweb filters without having to install Icon. Finally, version 2.7 contains some bug fixes and a number of small improvements in the HTML support. Noweb is available from CTAN (ftp.shsu.edu, ftp.tex.ac.uk, and ftp.uni-stuttgart.de) in directory /tex-archive/web/noweb. Norman Ramsey -- Norman Ramsey norman@bellcore.com ================================================================================ Archive-Date: Mon, 27 Feb 1995 17:44:33 CDT Sender: owner-litprog@SHSU.edu From: norman@flaubert.bellcore.com (Norman Ramsey) Reply-To: LitProg@SHSU.edu, norman@FLAUBERT.BELLCORE.COM Subject: Re: Which LitProg system? Date: 27 Feb 1995 22:04:42 GMT Message-ID: <3iti9q$4os@lowell.bellcore.com> CC: Gareth Rees To: LitProg@SHSU.EDU In article , Gareth Rees wrote: >I'm interested in a literate programming system satisfying the following >requirements: > > Programming Languages: any, especially LISP, C and SML > Target for documentation: Emacs Info, plain text (ASCII), HTML, and > Postscript > >I'd like to have a single source for the documentation, and generate >multiple targets from that source, including appropriate material for >each target. TexInfo's ability to have separate material in the Info >and TeX versions of a document seems perfect for this. Sounds pleasant. Noweb can get you close, but not there. If you mark up a noweb file using vanilla latex, you can run noweave and latex and get postscript out. Plus noweb can convert it to decent HTML, from which you can get reasonable plain text. But info doesn't fit in. >My best choice would appear to be to use Noweb, using TexInfo as my >markup language, and to write my own TexInfo back end. Probably. I don't know enough TexInfo to know whether you're better off using the latex or the HTML back end as a model. Norman ================================================================================ Archive-Date: Mon, 27 Feb 1995 20:08:59 CDT Sender: owner-litprog@SHSU.edu From: norman@flash.bellcore.com (Norman Ramsey) Reply-To: LitProg@SHSU.edu, norman@FLASH.BELLCORE.COM Subject: Re: Alternative LP Systems Date: 24 Feb 1995 04:11:29 GMT Message-ID: <3ijm9h$kvl@lowell.bellcore.com> To: LitProg@SHSU.EDU In article <3id1h2$mnq@martha.utk.edu>, Eric Lemings wrote: >Are there any LP systems that support PDL? PDL? Is this a Page Description Language? >Document languages other than TeX? Several tools support HTML. I recommend noweb and nuweb. >How about full blown, word processing, GUI interface systems? The problem is that the representations and formats used by modern WYSIWYG document-preparation tools range from undocumented to proprietary. For example, it's not clear whether automatic tools can insert indexing and cross-reference information into Frame Maker's MIF format without bollixing up the layout of the pages. The only public-domain WYSIWYG tool I know of, doc, is not competitive with commercial tools or with TeX. Norman ================================================================================ Archive-Date: Mon, 27 Feb 1995 20:26:35 CDT Sender: owner-litprog@SHSU.edu From: norman@flash.bellcore.com (Norman Ramsey) Reply-To: LitProg@SHSU.edu, norman@FLASH.BELLCORE.COM Subject: Re: Current status of NUWEB? Date: 24 Feb 1995 04:27:58 GMT Message-ID: <3ijn8e$l81@lowell.bellcore.com> CC: preston@tera.com To: LitProg@SHSU.EDU In article <9505410.3366@mulga.cs.mu.oz.au>, Stephen Edward Simmons wrote: >While reading the manual for NUWEB, I decided that there >was one aspect of it that I would like to change. > > the LaTeX formatting for the WEB source code is rigidly defined >in NUWEB's source code. This means that there is no simple way of >redefining the visual appearance of NUWEB's LaTeX output without altering >the source code and redefining. (to change, for example, 'scrap' to >'section' and use something other than a diamond to mark the end of >each section.) I don't want to put words into Preston's mouth, but let's look at the consequences of his decision: - the generated .tex files can be mailed anywhere on the net, and they just work with any vanilla latex installation --- no special macro files needed. - nuweb programs look the same anywhere in the world. - It's hard for people to tinker with the appearance of the TeX document, so they might spend their time on something more productive, like writing better documentation or building that C++ cross-refernecer I've been wanting :-) I took a different approach in noweb. the document is represented in an `intermediate form' that is easy to translate into latex or HTML, and I provided a custom macro package for noweb documents. What are the consequences: - I had to write a lot of crufty latex code. It's really embarrassing. I cringe when I have to change this code. - The latex code has lots of macros and hooks to change the appearance of documents, which makes the system more complicated. - Even worse, a bunch of appearance-related options found their way onto the noweave man page, which has reached the embarrassing stage. - Noweb is harder to install --- you have to have write permissions on the directory where latex styles and packages live. Having said all that, noweb may still be the way to go if you want something customizable. You might have better luck starting from Dave Hanson's `noweave.simple' back end than by trying to modify the existing macro package. Norman Ramsey ``If I ever find time to do it over, I'll do it better...'' ================================================================================ Archive-Date: Tue, 28 Feb 1995 05:56:26 CDT Sender: owner-litprog@SHSU.edu Date: Tue, 28 Feb 95 05:54:43 CST From: dhein@Onramp.NET Reply-To: LitProg@SHSU.edu, dhein@ONRAMP.NET Subject: RE: Hello! To: LitProg@SHSU.edu, Blitherakt Message-ID: MIME-Version: 1.0 Content-Type: MULTIPART/MIXED; charset=US-ASCII --- Content-Type: TEXT/PLAIN; charset=US-ASCII Check out the FAQ before posting here again. You might try a different comp.programming.* newsgroup. ---------------Original Message--------------- I've just started my subscription to this news group. SO!!! First of all, Hello! Now, down to business: A friend and I are looking for some people with IBM PC systems and C/C++,Assembly, or just about anything else that is manageble (preferably not Simula, Forth, Lisp and the like) programming experience for an interesting (at least we think it is) venture. We would like to get a group (a "Think Tank", if you will) of programmers together to author some utilities and/or games via the Internet. The way this would operate is this: A detailed application description/specification form would be drawn up and distributed to the members who would pick and choose the portions they would like to work on. On a regular basis, code will be sent to Me and my associate for Compilation, merging, and bug reporting. Eventually, something that works should evolve! We would maintain a Database of all programmers, their addresses (Internet, home or whatever you wish), and the total contribution in meaningful lines of code (i.e. 19,999 line comment blocks will be excluded). When (or should I say, IF) the programming project is released, everyone who made contributions to the project will be mentioned in the code and will be paid based on that contribution. We haven't worked out the method of payment yet (whether it will be like a quarterly royalty or a lump sum payment) as we're trying to get a feel for the interest in this kind of venture. We also feel that it would be ideal for the "Weekend Warrior" type of programmer; one who programs on a piecemeal basis for enjoyment of programming. If this sounds good to you, or you just have some general comments or suggestions, please send them to: Blitherakt@aol.com Looking forward to hearing from you! Tim Adamec aka Blitherakt ----------End of Original Message---------- ------------------------------------- Name: Dave Hein E-mail: dhein@onramp.net Date: 02/28/95 Time: 05:54:43 ------------------------------------- --- Content-Type: TEXT/PLAIN; SizeOnDisk=58134; name="LITPROG.TXT"; CHARSET=US-ASCII Content-Description: LITPROG.TXT Path: bloom-beacon.mit.edu!senator-bedfellow.mit.edu!faqserv From: thompson@sun1.coe.ttu.edu Newsgroups: comp.programming.literate,comp.answers,news.answers Subject: comp.programming.literate FAQ Supersedes: Followup-To: comp.programming.literate Date: 16 Jan 1995 10:46:05 GMT Organization: Texas Tech University, Lubbock, Texas, USA Lines: 1543 Approved: news-answers-request@MIT.Edu Distribution: world Expires: 14 Feb 1995 10:45:13 GMT Message-ID: Reply-To: thompson@sun1.coe.ttu.edu NNTP-Posting-Host: bloom-picayune.mit.edu Summary: Literate Programming FAQ--general introduction to the concepts of literate programming and the tools available to write literate programs. X-Last-Updated: 1994/08/23 Originator: faqserv@bloom-picayune.MIT.EDU Xref: bloom-beacon.mit.edu comp.programming.literate:1836 comp.answers:9537 news.answers:33215 Archive-name: literate-programming-faq Last-modified: 1994/08/23 Version: 1.1.10 Welcome to the Literate Programming Frequently Asked Questions List ------------------------------------------------------------------- This version was created Tuesday, August 23, 1994, and should considered stale after 90 days. Information contained in this document is the best available at preparation. The original file was dated October 15, 1993 (just for historical purposes). 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." Copyright 1993, 1994 David B. Thompson. All rights reserved worldwide. Permission is granted to copy this document for free distribution so long as it remains intact and unmodified. For other arrangements, contact the author/maintainer via email: thompson@sun1.coe.ttu.edu. What's New? ----------- + Add Fold2Web entry. + Correct noweb.el entry. (Thanks Dominique!) + Update nuweb.el entry. + Update SchemeWEB entry. + Update WWW and literate programming entry. + Update c2cweb entry. = ====================================================================== * 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, who can be reached at: thompson@sun1.coe.ttu.edu * Preferred mailing address for FAQ related comments/questions. wqdbt@ttacs1.ttu.edu * Forwarded to my pc. Comment and constructive criticism is 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 not be complete for some months. Nevertheless, the information contained herein may be useful to some. Use it as it is intended. - ---------------------------------------------------------------------- - Typography ------------ Major sections of the FAQ are divided by double lines (====). Minor sections and other divisions are separated by single lines (----). Major topics use a "* " as a leader. Minor topics use a "- " as a leader. This should simplify searching for topics. = ====================================================================== Table of Contents: ------------------ * Introduction, or "What's this all about?" - Typography * How do I get the FAQ? - Literate Programming FAQ - FWEB FAQ * Is there a newsgroup? (The comp.programming.literate newsgroup) * What internet nodes are of interest to literate programmers? * What is literate programming? * How do I begin literate programming? * What literate programming tools are available and where are they? - APLWEB - AWEB - CLiP - CWEB - FunnelWeb - FWEB - IMPACT - lit2x - Literate Programmer's Workshop (LPW) - MapleWEB - MWEB (Schrod/Detig) - MWEB (Sewell) - noweb - nuweb - ProTeX - RWEB - SchemeWEB - Spidery WEB - WEB - WinWordWEB * Are there other tools I should know about? - C2LaTeX - c2cweb - c2man - cnoweb - Fold2web - FunnelWeb mode - noweb.el - nuweb.el - TIE - Web mode * What other resources are available? - World Wide Web - TeX Resources - Virtual Coursework * Are there any code examples? - Examples included with developer's tools - Cameron Smith's KR-CWEB - Stanford GraphBase * Bibliographies. * How to anonymously ftp. * Acknowledgements. * End notes. = ====================================================================== * How do I get the FAQ? ----------------------- - 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.") An alternative is to use the fileserver at Sam Houston State University (SHSU). Send a message to FILESERV@SHSU.EDU and include in your message: SENDME LITPROG.FAQ The file server will forward a copy of the file to you via email. - ---------------------------------------------------------------------- - FWEB FAQ ---------- Marcus Speh maintains the FWEB FAQ. The current version number is 1.29. It can be retrieved in the same way as this FAQ; either by anonymous ftp or through the SHSU file server. On the SHSU server, the file name is FAQ.FWEB. Invoke your ftp software, open a connection to NIORD.SHSU.EDU [192.92.115.8], attach to the directory FAQ, and transfer the file FAQ.FWEB. Alternatively, send a message to the file server, FILESERV@SHSU.EDU, and include the following text in a one line message: SENDME FAQ.FWEB The file server will send the current version of the file via email. 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 (LPA) in the directory LPA/Documentation/faq/fweb (see the references to LPA below for more information). Also, Marcus Speh is looking for someone willing to take over the FWEB FAQ. The text of his email message follows... "Please add to the FWEB FAQ the note that I am looking for someone to take the maintenance of the FAQ over - I am ready to assist in any way whatsoever, including tons of mail, notes for v1.29->v1.30, Texinfo sources, a WWW server and Hypertextification etc." If you're interested, send mail to marcus@x4u2.desy.de and express your willingness to serve. = ====================================================================== * Is there a newsgroup? ----------------------- One of the most important resources is the literate programming newsgroup, comp.programming.literate. You can read this newsgroup using your standard reader. Altenatively, the newsgroup is gated to a mailing list hosted by George Greenwade and Sam Houston State University. You can subscribe by sending mail to the list-server, LISTSERV@SHSU.EDU, and include in the message one line of text: SUBSCRIBE LITPROG "your name in quotes" The list is unmoderated; messages sent to litprog@shsu.edu are automatically distributed to all subscribers and cross-posted to comp.programming.literate. Archives of the mailing list and newsgroup are maintained on niord.shsu.edu [192.92.115.8] in the directory litprog. = ====================================================================== * 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. The CTAN sites are: ftp host IP CTAN root Institution and Sponsor ------------------------------------------------------------------------- ftp.tex.ac.uk 134.151.79.32 pub/archive Aston Univ./UK TeX U.G. ftp.dante.de 129.206.100.192 soft/tex DANTE e.V. ftp.shsu.edu 192.92.115.10 tex-archive Sam Houston State Univ. Other nodes and directories of interest include: Node: niord.shsu.edu [192.92.115.8] Directory: various (do some snooping!) Notes: Has a gopher server. 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/ = ====================================================================== * 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 programmer, who wants to provide the best possible documentation 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 document such a program we want to explain each individual part of the web and how it relates to its neighbours. The typographic 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 combining the two, we can develop a style of programming that maximizes our ability to perceive the structure of a complex piece of software, and at the same time the documented programs 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 = ====================================================================== * 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. = ====================================================================== * What literate programming tools are available and where are they? ------------------------------------------------------------------- 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. :-) - ---------------------------------------------------------------------- - 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. - ---------------------------------------------------------------------- - 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. - ---------------------------------------------------------------------- - CLiP ------ Developer: E.W. van Ammers and M.R. Kramer Version: Unknown Hardware: Vax/VMS, Unix, and MS-DOS Languages: Any programming language. Formatter: Any formatter (TeX, LaTeX, Troff, Runoff, etc) or any wordprocessor including WYSIWYG systems (Word Perfect, Win Word, Ami Pro, Word, etc.) Availability: Anonymous ftp from: sun01.info.wau.nl:/CLIP/ms_dos MS-DOS version sun01.info.wau.nl:/CLIP/vax_vms VAX/VMS version CTAN:/web/clip LPA:/machines/ms-dos LPA:/machines/vax Readme: With bundle above Description: CLiP does not use explicite commands to perform the extraction process. Rather it recognizes pseudostatemens written as comments in the programming language in question. CLiP distinguishes pseudostatments from ordinary comments because the former comply with a 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 but we have not yet experimented with this form of documentation. 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 documentatio 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 segements. + 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: ammers@rcl.wau.nl - ---------------------------------------------------------------------- - 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 Note: A fork of CWEB 3.x was developed by Marc van Leeuwen which implements several changes to CWEB. It is available for anonymous ftp from ftp.cwi.nl:pub/cweb. The principle changes are: - Scans include files for typedef definitions - Grammar and formatting rules are well separated, allowing for run-time selection of a rule set (via command line option) - New manual. - ---------------------------------------------------------------------- - 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. - ---------------------------------------------------------------------- - FWEB ------ Developer: John A. Krommes Version: 1.30a (1.40 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: Plain TeX and LaTeX. 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 - ---------------------------------------------------------------------- - 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. - ---------------------------------------------------------------------- - lit2x ------- Developer: Unknown Version: Unknown Hardware: Unknown Languages: Unknown Formatter: Unknown Availability: Anonymous ftp from: LPA:/independent Readme: Unknown Description: None available Support: Unknown - ---------------------------------------------------------------------- - 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. - ---------------------------------------------------------------------- - MapleWEB ---------- Developer: Unknown Version: Unknown Hardware: Unknown Languages: Maple Formatter: Unknown Availability: Anonymous ftp from: LPA:/maple Readme: Unknown Description: None Support: Unknown - ---------------------------------------------------------------------- - 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. - ---------------------------------------------------------------------- - 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. - ---------------------------------------------------------------------- - noweb ------- Developer: Norman Ramsey Version: 2.6 Hardware: Unix and DOS platforms. Languages: All programming languages. Formatter: Plain TeX, LaTeX, and HTML (Mosaic) formatters. Availability: Anonymous ftp from: CTAN:/web/noweb LPA:/independent DOS version also in LPA:/machines/ms-dos also bart.kean.edu:/pub/leew Last recourse, use bellcore.com:/pub/norman Readme: With bundle above. Description: noweb is designed to meet the needs of literate programmers while remaining as simple as possible. Its primary advantages are simplicity, extensibility, and language-independence. noweb uses 5 control sequences to WEB's 27. noweb now supports indexing and identifier cross-reference, including hypertext ``hot links'' courtesy of Mosaic. The simple noweb manual is only 2 pages; documenting the full power of noweave and notangle requires another 3 pages. noweb works ``out of the box'' with any programming language, and its formatter-dependent part is a 60-line nawk program. The primary sacrifice relative to WEB is the loss of prettyprinting. Support: email to the author - ---------------------------------------------------------------------- - 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 - ---------------------------------------------------------------------- - ProTeX -------- Developer: Eitan Gurari Version: 1.1 (AlProTeX 1.2) Hardware: Any platform with TeX (ProTeX is written in TeX) Languages: Any language Formatter: TeX and LaTeX Availability: Anonymous ftp from: ftp.cis.ohio-state.edu : pub/tex/osu/gurari/ LPA:/independent Readme: Unknown Description: There is a book published on using ProTeX, @Book{Gurari:TLD94, author = "Eitan M. Gurari", title = "{\TeX} and {\LaTeX}: Drawing and Literate Programming", publisher = pub-MH, year = "1994", address = pub-MH:adr, bibdate = "Wed Sep 29 17:55:14 1993", acknowledgement = ack-nhfb, } Support: gurari@cis.ohio-state.edu - ---------------------------------------------------------------------- - 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 - ---------------------------------------------------------------------- - 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. - ---------------------------------------------------------------------- - 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. - ---------------------------------------------------------------------- - 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. - ---------------------------------------------------------------------- - 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. = ====================================================================== * 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. - 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. - ---------------------------------------------------------------------- - c2cweb -------- Developer: Werner Lemberg Version: 1.4 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 - ---------------------------------------------------------------------- - c2man ------- Developer: Graham Stoney Version: 2.0 patchlevel 26 Hardware: Unix, MSDOS, OS/2. Languages: C Formatter: nroff -man, texinfo (requires yacc/byacc/bison, lex/flex, and nroff/groff/texinfo/LaTeX). Availability: Anonymous ftp from ftp.wustl.edu: /usenet/comp.sources.reviewed/volume03/c2man* ftp.informatik.uni-stuttgart.de: /pub/archive/comp.sources/reviewed/c2man* Readme: See distribution. Description: The primary philosophy here is to use the programming language as far as possible to express the programmer's intentions, and to use comments only when the programming language is not sufficiently expressive. A comment can then become part of the language grammar which is recognised by a "documentation compiler". This tool parses a superset of the programming language and can automatically generate documentation in human-readable form by associating the programmer's comments with the objects in the code by their context. Support: Actively supported; mailing list available: send "subscribe c2man " (in the message body) to listserv@research.canon.oz.au. - ---------------------------------------------------------------------- - 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. - ---------------------------------------------------------------------- - 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 - ---------------------------------------------------------------------- - Funnelweb Mode ---------------- Developer: Daniel Simmons Version: Unknown Availability: Litprog archives (was in email) Anonymous ftp from: ftp.imada.ou.dk 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 - ---------------------------------------------------------------------- - 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 - ---------------------------------------------------------------------- - 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@sunbim.be - ---------------------------------------------------------------------- - TIE ----- Developer: Unknown Version: Unknown Hardware: Unknown Availability: Anonymous ftp from: LPA:/Tools Readme: Unknown Description: This software merges change files. Support: Unknown - ---------------------------------------------------------------------- - 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 = ====================================================================== * What other resources are available? ------------------------------------- - 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 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 ftp.desy.de [131.169.10.115] and get the file: /pub/userWWW/projects/Announce/LitProg.txt - ---------------------------------------------------------------------- - TeX Resources --------------- Another resource of interest to literate programmers is the info-tex mailing list. If you're using (La)TeX as your typsetting system and have access to internet, then you should investigate this mailing list. Mail list service is available through the SHSU list-server. To subscribe, send a message to LISTSERV@SHSU.EDU, and include in the message one line of text: SUBSCRIBE INFO-TEX "your name in quotes" The list is unmoderated; messages sent to info-tex@shsu.edu are automatically distributed to all subscribers and cross-posted to comp.text.tex. Archives of the mailing list and newsgroup are maintained on niord.shsu.edu [192.92.115.8] in the directory info-tex. 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. - ---------------------------------------------------------------------- - Virtual Coursework -------------------- Marcus Speh plans an introductory course on Literate Programming on the Internet, part of the first semester of "Global Network Academy" [GNA], a non-profit corporation incorporated in the state of Texas, affilated with the Usenet University project. The texts/sample programs for this class will be made available via the World-Wide Web. A special room on GNA Virtual Campus will be staffed by a consultant in one to two hour shifts. Students with questions can telnet to the virtual campus and ask questions of the staff there. If you are interested in registering for the course either as a student or as a consultant, please contact marcus@x4u.desy.de. You will receive a standard reply message; no further action will be taken until June 94. Interested parties can check the hypertext notes for the completed C++ Course done in a similar fashion, at URL http://info.desy.de:80/pub/uu-gna/html/cc/index.html [Editor's note: Because of workload, Marcus requests that email inquiries be limited to a statement of interest for either a student or consultant position until June 1994.] = ====================================================================== * 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: bart.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 written in (Levy/Knuth) CWEB. More details in the distribution. It is available via anonymous ftp from: labrea.stanford.edu:/pub/sgb = ====================================================================== * 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 several 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. = ====================================================================== * 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. = ====================================================================== * 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. = ====================================================================== * 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. = End of File ========================================================== ----- ================================================================================ Archive-Date: Tue, 28 Feb 1995 13:34:47 CDT Sender: owner-litprog@SHSU.edu From: kencham@ulysses.cs.umn.edu (deepak r. kenchammana-hosekote) Reply-To: LitProg@SHSU.edu, kencham@ULYSSES.CS.UMN.EDU Subject: Slides for LP talk? Message-ID: Date: Tue, 28 Feb 1995 16:10:11 GMT To: LitProg@SHSU.EDU Hi, Six months back I found out about literate programming and since then have been a regular user of it. I have been trying to "spread the word around" in my research group and have found about 10-15 people who are enthusiastic to hear/learn about it. As a result I have planned to give them a 1hr talk on literate programming and some of the freely available litprog tools. I was wondering if anyone of you had given similar talks. If so, then I was wondering if you would be willing to share your slides/viewgraphs. The talk is on Friday. If you have slides and are willing to share them then please pass them to me before then. Thanks! \d. -- "What's done cannot be undone" - Macbeth, V.1(pre-emacs) "What's done can be C-/-ed" - Macbeth, V.1(post-emacs)