Archive-Date: Sat, 02 Jan 1993 18:45:14 CST Date: Tue, 29 Dec 92 18:46:40 CST From: bart@cs.tamu.edu (Bart Childs) Reply-To: LitProg@SHSU.edu Message-ID: <9212300046.AA13837@neuron.cs.tamu.edu> To: litprog@shsu.edu Subject: Literate Programming without TeX Thimbleby wrote a CWEB using C and troff. I am sure it is available on some archives somewhere. A reference to a paper is: Harold~Thimbleby, ``Experiences of `Literate Programming' using CWEB (a variant of Knuth's WEB),'' The Computer Journal, vol.~29, no.~3, pp.~201--211, Jun.~1986. I believe he was at York at that time and is now at Stirling. I never looked at it in great detail because the information I heard was that it proved that troff was extremely limiting. I suppose that the wide availability of TeX on unix boxes and the availability of Levy's CWEB also made it not nearly as desirable. Bart Childs ================================================================================ Archive-Date: Mon, 04 Jan 1993 06:03:58 CST From: Joachim Schrod Reply-To: LitProg@SHSU.edu Message-ID: <9301041204.AA15892@hp5.iti.informatik.th-darmstadt.de> Subject: Re: VHDL Literate harware modeling ? To: LitProg@SHSU.edu Date: Mon, 4 Jan 93 13:04:23 MEZ steve wrote: > > Of course, there is a small problem that I have with this. > Normally I do my designs (VLSI that is), bottom up. A web, on the other > hand, usually appears as a top down design. It's often used so, but not necessarily. You can define program parts before you use them. So a bottom-up design may be done as well, without any loss. Actually, DEKs WEB programs (ie, WEB itself, TeX, METAFONT, etc.) are an example of bottom-up design. I left it to the generous reader to decide about the quality of this program design. ;-) A happy and peaceful new year Joachim ================================================================================ Archive-Date: Mon, 04 Jan 1993 14:35:53 CST Date: Mon, 4 Jan 93 14:34:31 CST From: mcguire@cs.tamu.edu (Tim McGuire) Reply-To: LitProg@SHSU.edu Message-ID: <9301042034.AA24433@neuron.cs.tamu.edu> To: LitProg@shsu.edu Subject: Re: Literate Programming without TeX Allen Holub's Arachne system is available from the author (holub@violet.berkeley.edu) for a fee and runs on some kind of PC system. In his words (from a longer correspondence to me in June 1990): I wrote Arachne myself in order to write Compiler Design. It became clear as soon as I started that some sort of WEB-like preprocessor would be necessary for me to maintain my sanity, so I wrote a small one which has gradually expanded to a pretty powerful tool. I haven't written it up anywhere yet, however. The language is C and the formatting language is troff. It is not a derivative of Thimbleby's cweb system; it was directly inspired by Knuth's original WEB. My personal evaluation, based strictly on the Compiler Design book and correspondence with Holub, is that Arachne does fit the literate paradigm. In general, it appears that Arachne encourages larger code modules than does WEB, and thus the degree of code/documentation integration is not as high. Comments from anyone who has used Arachne would be greatly appreciated. Tim McGuire mcguire@cs.tamu.edu ================================================================================ Archive-Date: Mon, 04 Jan 1993 19:16:14 CST Date: Mon, 4 Jan 93 18:14:42 MST From: gilligan@central.bldrdoc.gov (Jonathan M. Gilligan) Reply-To: LitProg@SHSU.edu Message-ID: <9301050114.AA27195@central.bldrdoc.gov> To: litprog@shsu.edu Subject: conditional processing and @d in CWEB Here's an item for the wish list for a future release of CWEB: I sometimes want to conditionally define a preprocessor macro that I define with an @d in the definition block of a section. I can work around this problem by using change files or by moving the definition to the C block of that section, but it would be nice to be able to have a variant of @d that would allow me to conditionally define a macro. I'd like to be able to write a web containing something like @? if defined(TEST) @d BAR foo @? else @d BAR fu @? endif (or something similar) and have it tangle into #if defined(TEST) #define BAR foo #else #define BAR fu #endif I know that I can just stuff my conditional definitions into the C block of a section, but that's not always elegant, since I can have a number of definitions that logically belong together in the definition block of the section. I'd like to know what other (more experienced) literate programmers think. What would the preferred syntax be for such an extension? Is it better to leave CWEB as it now is and move my conditional definitions or use change files (this gets annoying when there are conditional definitions in an included file such as common.h)? Is there a better solution already out there or in the wings? ---Jon Disclaimer --- The government probably disagrees with my opinions. ================================================================================ Archive-Date: Mon, 04 Jan 1993 22:21:46 CST Date: Tue, 5 Jan 93 03:56:44 GMT From: mfy@sli.com (Mike Yoder) Reply-To: LitProg@SHSU.edu Message-ID: <9301050356.AA14815@ravel.sli.com> To: LitProg@SHSU.edu Subject: conditional processing and @d in CWEB Jonathan M. Gilligan wrote, as a prelude to a question: >I sometimes want to conditionally define a preprocessor macro... >... something like > >@? if defined(TEST) >@d BAR foo >@? else >@d BAR fu >@? endif > >(or something similar)... I can't necessarily answer your question the way you would like, since I can't read your mind from here; so I will just answer to what seems to be your principal interest. I use a processor in which every feature (with two very small exceptions) was added only in response to a need, or at least a strong desire. (The two exceptions are underlining and overstriking of text.) It still has no macro processing; but conditionals were among the very first items implemented. There are certainly a number of minor problems that could be solved well by simple macros; but I'd advise a designer of such a tool to shy away from elaborate macro processors. Macros tend to be hard to debug; but besides this, their presence tends to prevent simpler and better solutions from being implemented when a clever but convoluted macro solution can be found. (And macro processors still tend to be slow.) I do expect to eventually add macros, but not soon. I have some empirical evidence for this claim. When I worked at Apollo (this was before and during the merger with HP) I sent a survey to the users of this tool: it was a list of possible new features plus a request to rate each one on a scale of 0 to 10 for perceived usefulness. I totaled the scores from each response (there were 6 responses) to get an overall score, which I have used since then to guide my implementation. The scores fell into obvious groups: 0-1, 9, 17-19, etc. up to a high score of 39. "Simple macros" was in the 0-1 group, which surprised me a great deal until I thought about it. In the simplest case, your problem could be solved in Inscribe by writing @option bar = foo, fu; ... @bar() In more complex cases you would need to use @case(bar) ... @end-case(bar). The history of this method might be of interest: Inscribe came into existence to support an Ada compiler effort which started in 1983. When first implemented, there were just two commands, @case-host and @case-target: only two options were allowed, and their names were "wired in." At some point much later, a third option became needed, and at that point it became clear that a third special case (no pun intended) would be a bad idea. I find the @case...@end-case construct (with what is essentially an enumeration type as the selector type) much more natural than the rather stilted conventions used in C preprocessor conditionals. It is certainly less error-prone: you cannot accidentally turn on two of the supposedly mutually exclusive options, or leave them all turned off because the option you tried to turn on didn't exist. So: my recommendation to writers of literate programming tools is to implement case statements as your primary mode of expressing conditionals in the program. ================================================================================ Archive-Date: Tue, 05 Jan 1993 08:14:23 CST Date: Tue, 5 Jan 93 07:21:54 GMT From: mfy@sli.com (Mike Yoder) Reply-To: LitProg@SHSU.edu Message-ID: <9301050721.AA16360@ravel.sli.com> To: LitProg@SHSU.edu Subject: mail without signature My apologies for the mail message without a signature. The reply to Jonathan Gilligan which talked about conditionals vs. macros was mine. Michael F. Yoder [mfy@sli.com] ================================================================================ Archive-Date: Tue, 05 Jan 1993 08:22:34 CST Date: Wed, 23 Dec 92 12:31 EST From: Jeff Rummel Reply-To: LitProg@SHSU.edu Subject: cnoweb problem To: LITPROG@SHSU.edu Thanks to Z.Wagner (I think, I lost the note I got, but remebered the advice) for pointing me in the right direction. I now have cnoweb.tex able to print out individual foo.c files and also to print a file that looks like /* ãinput cnoweb.tex ãtitle{All source code for the project} blah blah blah (introduction overview that starts the listings) ãstartmodules ãprintmodule{foo1.h} ãprintmodule{foo1.c} ... etc ... ãendmodules */ Now I get all the separate source code files to print with one master table of contents. There are a few spurious /* here and there, but I can live with those for now. The key was the use of ãaftergroup in defining ãprintmodule: ãdefãprintmodule#1{ãaftergroup/ãaftergroup*ãbegingroupãinput #1 ãendgroupãendgroup} (I wasn't too sure why I needed two ãendgroup's, but it works and I have other things to do...) If anyone wants to see the modified file (and if you clean up some of the loose ends, that would be great), drop me a note and I'll send it to you. --jeff. ps. I'll be out of town for the next week or so -- don't expect to see a response until 1993. ================================================================================ Archive-Date: Tue, 05 Jan 1993 15:45:04 CST Message-ID: <9301051531.AA21769@mistral.imag.fr> From: Yves Arrouye Reply-To: LitProg@SHSU.edu Date: Tue, 5 Jan 1993 16:31:59 +0100 To: LitProg@SHSU.edu Subject: contacting the author of fweb Does anyone has the email of fweb's author? Thanks in advance. -- Elle e'tait comme je vous la raconte sans que vous Yves Arrouye puissiez voir son visage ni entendre ses paroles, arrouye@mistral.imag.fr pas plus que je ne l'ai vu ni ne les ai entendues, arrouye@imag.imag.fr moi qui pourtant les ai si bien connus. (33) 76 57 48 61 ================================================================================ Archive-Date: Tue, 05 Jan 1993 20:40:44 CST Date: Tue, 05 Jan 1993 20:58:36 EST From: "Edward F. Keith" Reply-To: LitProg@SHSU.edu Message-ID: <2b4a3cd4.efkport@efkport.kew.com> To: "Literate Programming List" Subject: lc++ Is anyone familiar with Macro S. Hyman's lc++? It was presented in the July 1990 Computer Language and is written in Awk. -Ed K. -- Ed Keith Telephone: 1(703)370-5217 U.S. Snail: 4535 Taney Ave. #201 Internet : ed@efkport.kew.com Alexandria, VA 22304 I am I, Don Quixote, The Lord of La Mancha . . . ================================================================================ Archive-Date: Tue, 05 Jan 1993 20:42:39 CST Date: Mon, 04 Jan 1993 21:13:39 EST From: "Edward F. Keith" Reply-To: LitProg@SHSU.edu Message-ID: <2b48eedb.efkport@efkport.kew.com> To: "Literate Programming List" Subject: Literate Programming Why should I take the time to learn CWEB? What is the advantage of literate programming over extensive commenting and good design in a traditional language? I do most of my work in C. I write short functions, each with a descriptive header explaining what it does and how it does it. I comment each of the parameters and all variables when they are declared. I then run the code through a code formatter and cross reference generator. I still find the code hard to read three months later. I read the article in the Jan. 1993 Computer Language, and have been following this list for several weeks. I find the listings in CL and posted here even harder to read than most C code (This is probably because I have been reading C for eight years, and saw CWEB for the first time last month). In the article Silvio Levy says, "The gain in clarity obtained by using Cweb over C should now be obvious." Maybe I'm a little slow. Could someone please explain it to me? -Ed K. -- Ed Keith Telephone: 1(703)370-5217 U.S. Snail: 4535 Taney Ave. #201 Internet : ed@efkport.kew.com Alexandria, VA 22304 I am I, Don Quixote, The Lord of La Mancha . . . ================================================================================ Archive-Date: Wed, 06 Jan 1993 06:28:26 CST Date: Wed, 6 Jan 93 08:50:51 GMT From: steve@vnet.ibm.com Reply-To: LitProg@SHSU.edu To: litprog@shsu.edu Subject: hi unsubscribe litprog ================================================================================ Archive-Date: Wed, 06 Jan 1993 06:44:35 CST Date: Wed, 6 Jan 93 09:12:47 +0100 From: marcus@x4u.desy.de (Marcus Speh) Reply-To: LitProg@SHSU.edu Message-ID: <9301060812.AA29922@x4u.desy.de> To: LitProg@SHSU.edu Subject: contacting the author of fweb References: <9301051531.AA21769@mistral.imag.fr> Yves> Does anyone has the email of fweb's author? The author of FWEB is John A. Krommes . For FWEB, there is a list of Frequently Asked Questions (FAQ),too. The old version is at niord.shsu.edu in [FILESERV.FWEB]. The next version of this FAQ (with many changes) will be posted to LitProg beginning of next week. --Marcus Speh -- ================================================================================ Archive-Date: Wed, 06 Jan 1993 07:51:49 CST Message-ID: <9301061350.AA03413@mistral.imag.fr> From: Yves Arrouye Reply-To: LitProg@SHSU.edu Date: Wed, 6 Jan 1993 14:50:44 +0100 To: Litprog@SHSU.edu Subject: manrefs.tex for fweb 1.30 user's manual? Hi, I got the version 1.30 of fweb from lyman.pppl.gov but I can't find the manrefs.tex file in order to print the manual... Does anybody know where I can find it? (It seems to define \cite and other macros for TeX). Yves. -- Elle e'tait comme je vous la raconte sans que vous Yves Arrouye puissiez voir son visage ni entendre ses paroles, arrouye@mistral.imag.fr pas plus que je ne l'ai vu ni ne les ai entendues, arrouye@imag.imag.fr moi qui pourtant les ai si bien connus. (33) 76 57 48 61 ================================================================================ Archive-Date: Wed, 06 Jan 1993 09:30:21 CST Date: Wed, 6 Jan 93 08:31:20 MST From: kml@ctrss1.lanl.gov (Kuok Mee Ling) Reply-To: LitProg@SHSU.edu Message-ID: <9301061531.AA02080@ctrss1.lanl.gov.lanl.gov> To: LitProg@SHSU.edu Subject: Re: contacting the author of fweb You can contact John Krommes at krommes@princeton.edu ================================================================================ Archive-Date: Wed, 06 Jan 1993 09:33:09 CST Date: Wed, 6 Jan 93 16:33:23 +0100 From: marcus@x4u.desy.de (Marcus Speh) Reply-To: LitProg@SHSU.edu Message-ID: <9301061533.AA05885@x4u.desy.de> To: LitProg@SHSU.edu Subject: manrefs.tex for fweb 1.30 user's manual? References: <9301061350.AA03413@mistral.imag.fr> From the READ_ME file in: /anonymous@lyman.pppl.gov:/pub/fweb: ------------------------------------------------------------------- VERY IMPORTANT NOTICE (January 5, 1993): The directory /pub/fweb/v1.30 is NOT READY for release yet. That will ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ happen in a few days. Meanwhile, a few select people are testing it. ------------------------------------------------------------------------------- Got it? Get the manual and all this from the directory "v1.23/manual"! --Marcus Speh -- ================================================================================ Archive-Date: Wed, 06 Jan 1993 10:09:02 CST Subject: To: litprog@shsu.edu Date: Wed, 6 Jan 1993 17:09:34 +0100 (MET) From: Hubert Hofmann Reply-To: LitProg@SHSU.edu Sender: hofmann@ifi.unizh.ch unsubscribe litprog ================================================================================ Archive-Date: Wed, 06 Jan 1993 17:24:46 CST Message-ID: <199301062322.AA15023@mucket.vast.unsw.edu.au> To: Literate Programming Mailing List CC: stevea@vast.unsw.edu.au Subject: Comment on behaviour of weave Date: Thu, 07 Jan 93 10:22:46 +1100 From: stevea@vast.unsw.edu.au Reply-To: LitProg@SHSU.edu Hi all, This message is really intended just to solicit opinions on the behaviour of weave (well cweave of both CWEB and Spidery WEB - others may perform similarly though). At the moment, if I use the following code: @ This is just an example. @= typedef ASCII char; @= ASCII letter; It weaves to: 1. This is just an example. = typedef ASCII char; =ASCII letter; This is not exactly how I want weave to behave, and my preferred woven output should be obvious. This type of code also tangles to the undesired output (although I must admit at least CWEB ctangle complains - I'm not sure about Spider). Now for all I know, some people using weave might take advantage of this "feature". What I would like to know is what output people prefer: the current output, or my preferred output. If people don't actually make use of this "feature", I'll probably hack around and try to "fix" it. Any comments? cheers -steve ================================================================================ Archive-Date: Wed, 06 Jan 1993 20:02:23 CST Message-ID: <9301070200.AA05369@hydrus.mc.xerox.com> To: LitProg@shsu.edu Subject: Re: Literate Programming Date: Wed, 6 Jan 1993 18:00:30 PST From: "Marty Leisner" Reply-To: LitProg@SHSU.edu In message <2b48eedb.efkport@efkport.kew.com> you write: >Why should I take the time to learn CWEB? What is the advantage of >literate programming over extensive commenting and good design in a >traditional language? > >I do most of my work in C. I write short functions, each with a >descriptive header explaining what it does and how it does it. I >comment each of the parameters and all variables when they are >declared. I then run the code through a code formatter and cross >reference generator. I still find the code hard to read three months >later. > > >In the article Silvio Levy says, "The gain in clarity obtained by >using Cweb over C should now be obvious." Maybe I'm a little slow. >Could someone please explain it to me? > > -Ed K. I'm not sure about the gain in clarity...I have no problem reading quality C code months after the subject... I generally don't use a formatter...I just follow formatting rules... You really aren't supposed to look at the Webbed code (from what I've seen...you look at the formatted comments, and the computer looks at the code... I too am unsure whether its worth the time to learn and whether it improves readability (although I think TeXinfo is a "good" think -- having the documentation on line and printed). marty leisner@eso.mc.xerox.com leisner.henr801c@xerox.com Member of the League for Programming Freedom "People cannot be managed. Inventories can be managed, but people must be led" -- H. Ross Perot ================================================================================ Archive-Date: Wed, 06 Jan 1993 20:21:21 CST Message-ID: <9301070219.AA15484@neuron.cs.tamu.edu> Date: Wed, 6 Jan 93 20:16:09 -0600 From: bart@cs.tamu.edu Reply-To: LitProg@SHSU.edu To: LitProg@shsu.edu Subject: Re: Comment on behaviour of weave I would prefer that it stop cold! I think that only one @<----@>= should be allowed per section/module. Bart Childs ================================================================================ Archive-Date: Thu, 07 Jan 1993 09:45:15 CST Date: 7 Jan 1993 10:31:21 -0500 From: "Timothy Larkin" Reply-To: LitProg@SHSU.edu Subject: Re: Comment on behaviour o To: LitProg@SHSU.edu Reply to: RE>> Comment on behaviour of Bart Childs writes: >I think that only one @<----@>= >should be allowed per section/module. in response to the observation of stevea@vast.unsw.edu.au that cweb doesn't interpret correctly multiple @<----@>= per section. I have found many instances in which it would be useful and logical to have multiple code parts per section. For instance, I find that a code part often consists of a function definition which tangles into @. I would like to include a prototype at that point in the web which would tangle into @. I can do this only by introducing a dummy section with an empty TeX part, which offers no advantage to the reader or the writer. Again, I may find it appropriate to introduce a global variable, destined for @, in the same section in which I define a function, destined for @. Granted, such a license might be abused. But web offsers as one of the primary benefits to free the programmer from the arbitrary sequence of presentation demanded by compilers, e.g. variables and functions need to be typed before use. Thus in web, unlike C, rhetorical considerations determine the order of presentation. In this spirit, it would be logical to allow additions to multiple code parts within a single section if this localizes the presentation of related elements which the C compiler requires to appear in unconnected sections of the tangle. Tim Larkin tsl1@cornell.edu ================================================================================ Archive-Date: Thu, 07 Jan 1993 11:10:02 CST Date: Thu, 7 Jan 93 18:06:13 +0100 From: Roegel Denis Reply-To: LitProg@SHSU.edu Message-ID: <9301071706.AA11475@pandore.loria.fr> To: LITPROG@SHSU.edu Subject: bad CWEB formatting ? CC: roegel@pandore.loria.fr Hello, I am new to the list. I am just beginning to use CWEB and I have a formatting problem. Somewhere, I use a declaration like char line[100]; Ctangle gives me a correct C source that compiles without harm. However, Cweave formats me line as if it was a type, and you can imagine that the function where line is declared looks bad... Of course, I know that line is defined in C (K&R), but the word is not reserved. So, why does Cweave not understand ? Is there an other solution than changing the name of my string ? Thanks for your help. Denis. PS. I am running the TeX 3.14 distribution, etc. ================================================================================ Archive-Date: Thu, 07 Jan 1993 11:11:12 CST Message-ID: <9301071613.AA15041@im4u.cs.utexas.edu> From: leew@cs.utexas.edu (Lee Wittenberg) Reply-To: LitProg@SHSU.edu Date: Thu, 7 Jan 1993 10:13:56 -0600 To: LitProg@shsu.edu Subject: Re: Comment on behaviour of weave Steve Avery writes: > This message is really intended just to solicit opinions on the > behaviour of weave (well cweave of both CWEB and Spidery WEB - others > may perform similarly though). At the moment, if I use the following > code: > > @ This is just an example. > > @= > typedef ASCII char; > > @= > ASCII letter; > > It weaves to: > > 1. This is just an example. > > = > typedef ASCII char; > =ASCII letter; > > This is not exactly how I want weave to behave, and my preferred > woven output should be obvious. This type of code also tangles to the > undesired output (although I must admit at least CWEB ctangle complains > - I'm not sure about Spider). > Now for all I know, some people using weave might take advantage > of this "feature". What I would like to know is what output people > prefer: the current output, or my preferred output. If people don't > actually make use of this "feature", I'll probably hack around and try > to "fix" it. Aside from the fact that the typedef should be typedef char ASCII; it's an interesting problem. I use both Spidery WEB (which requires another @ before the second named section definition) and NOWEB (which doesn't). I have to admit that, though I like being able to define a new named section without having to remember about the @, I think I prefer it the way CWEB does it. One section, one definition seems like the right way to do things. -- Lee ================================================================================ Archive-Date: Thu, 07 Jan 1993 11:12:38 CST Message-ID: <9301071646.AA16653@im4u.cs.utexas.edu> From: leew@cs.utexas.edu (Lee Wittenberg) Reply-To: LitProg@SHSU.edu Date: Thu, 7 Jan 1993 10:46:52 -0600 To: LitProg@shsu.edu Subject: Re: Literate Programming Edward F. Keith writes: > Why should I take the time to learn CWEB? What is the advantage of > literate programming over extensive commenting and good design in a > traditional language? I can't speak for everyone, but there are 2 reasons why I switched to literate programming from reasonably well commented, fairly clean code. 1. Maintenance. Not only can I explain _why_ I'm doing something while I'm writing the code (these kind of explanations are not only awkward in normal programs, but often get in the way and overshadow the code), but I can also make little notes to myself about things that need to be changed, where an algorithm came from, etc (and put pointers to these notes in the index!). The index of identifiers is invaluable in trying to figure out someone else's code. In fact, my "Road to Damascus" came about when I was trying to get CWEB working on my PC. There was an obscure bug involving pointer arithmetic in CWEAVE. I spent a little over a week (during off-time at an ACM conference) poring over the woven listing, and found the bug. I would have given up on a non-literate program of similar size (and have on several). 2. Structure. Since TANGLE puts all the code sections in proper order, I can concentrate on writing the program in the order that I feel best for purposes of exposition. I can write the program for human beings, rather than for the compiler (I think this is the most important point of all). I can also modularize code without having to write a procedure (with its attendant overhead) by using a named section.\footnote{perhaps this is why Knuth used the term "module" in early versions} In any event, I won't do without my literate programming tools. I've recently had to do some programming in PAL (Paradox Application Language). When I discovered that Spidery WEB wasn't capable of dealing with PAL (through not fault of its own -- PAL is fairly insane), I downloaded NOWEB, adapted it to work under DOS (a rather painful process), and now use it for all my PAL work. Even the programmers in the office who do not use NOWEB have no problems reading the woven listings. Hope this goes a bit toward answering your question. The best advice I can give is: "Try it, you'll like it". -- Lee Wittenberg ================================================================================ Archive-Date: Thu, 07 Jan 1993 12:29:02 CST Message-ID: <9301071825.AA26503@neuron.cs.tamu.edu> Date: Thu, 7 Jan 93 12:22:24 -0600 From: bart@cs.tamu.edu Reply-To: LitProg@SHSU.edu To: litprog@shsu.edu Subject: Defining multiple modules (sections) in one I really don't consider it a big deal. I don't see what is wrong with @ documentation ... @= stuff @ @= more stuff That extra `@ ' gives unique module identifiers to the index entries in `Something' and `Something else'. Tim's example (Tim Larkin's response 7 Jan 93 -- 10:31 am) is one where this is not much help. I did a quick analysis of tex.web and find that Don Knuth had 505 occurrences of ``@ @<'' in tex.web and these reference 356 unique module names. Most of these are quite readable and this is due to the care he took in being consistent and descriptive in the names. They are not like `Something'. Incidentally, most came from `case' statements and only four of them were `@ @ To: LitProg@shsu.edu Subject: Arachne (was: LitPgm w/o TeX) I posted Allen Holub's e-mail address a few days ago in regard to his Arachne system. Apparently, you will get better response if you contact him via phone or snail-mail. I got the following when fingering his account: ------- [violet.berkeley.edu] Login name: holub In real life: Allen Holub You can also contact me C/O: Software Engineering Consultants PO Box 5679 Berkeley, CA 94705 telephone (415) 540-7954 (voice and FAX) It's best to call if you post email to make sure that I log on and read it. -------- Tim McGuire mcguire@cs.tamu.edu Institute for Scientific Computation Texas A&M University ================================================================================ Archive-Date: Thu, 07 Jan 1993 17:31:45 CST Message-ID: <199301072316.AA15566@mucket.vast.unsw.edu.au> To: LitProg@SHSU.edu CC: stevea@vast.unsw.edu.au Subject: Re: Comment on behaviour of weave Date: Fri, 08 Jan 93 10:16:04 +1100 From: stevea@vast.unsw.edu.au Reply-To: LitProg@SHSU.edu Hi all, I seem to be getting all sorts of comments on this one, so I'll field them all here rather than in separate messages. Be forewarned, there's a bit of me standing on my soap-box here and expounding my literate programming philosophy. Feel free to shoot holes in my philosophy, but don't flame me for philosophising - you were warned. First up, Timothy Murphy sez: me> This is not exactly how I want weave to behave, and my preferred me> woven output should be obvious. tim> Not obvious to me. Okay, I should elaborate a bit. Timothy Larkin has provided a much better example which I'll borrow (hope he doesn't mind). I'm frequently coding away, and come across a module/section which would be much more readable if I were able to include two @
= entries in it. Timothy's example would look like: @*Read a String. This function.... @= char *read_string() { ..... } @= char *read_string(); This would weave to: 12. Read a String. This function... += char *read_string() { ..... } += char *read_string(); Currently weave would produce: 12. Read a String. This function... += char *read_string() { ..... } <- char *read_string(); It makes a lot more sense to include the prototype in the same section as the definition. However, at present, it is not possible to do this with any of the weave's I've used (although Lee Wittenberg notes that noweb will treat it as I would like it to). The current behaviour of weave is definitely undesirable. I don't know how or why anyone would use a @<----@> section as part of an expression when there is provision for defining macros. So, I believe it should be changed one way or the other. It could either behave as I propose, or as preferred by Bart Childs , who sez: bart> I would prefer that it stop cold! I think that only one bart> @<----@>= bart> should be allowed per section/module. Lee Wittenberg also seems to agree with Bart's comments. Bart goes on (in a later message), to suggest the preferred solution to the problem should be: @*Read a String. ... @= char *read_string() ... @ @= char *read_string(); This uses an unnamed section to provide the extra chunk of code. Bart sez: bart> That extra `@ ' gives unique module identifiers to the index bart> entries in `Something' and `Something else'. Tim's example (Tim bart> Larkin's response 7 Jan 93 -- 10:31 am) is one where this is not bart> much help. I believe that there must be many other cases where the extra section identifier is not of that much use. Bart goes on to cite examples from tex.web by Knuth, where there are some 505 unnamed sections with no textual explanation which reference 356 unique section names. I'll go out on a limb here and say I don't much like Knuth's code. This is not so much due to the code itself, but more the restrictions placed on it by the original WEB. The code is very flat, as WEB does not make much provision for any notion of a program hierarchy. I code pretty much the way I was originally taught - top-down, decomposing the original problem into sub-problems, which are then further decomposed. This leads to the idea of a program hierarchy. But the original WEB only supported two levels of such an hierarchy, named and unnamed sections. This restriction in turn tends to lead to flat code, or at least code with no apparent hierarchy. If you look at Spider of FWEB (I believe) on the other hand, they support seven levels of a hierarchy (@*=,@*,@*1-@*4,@ ), which leads to a more intuitive programming style. (I still find this restrictive, however, and have modified spider and cweb to provide arbitrarily deep sectioning, but thats another story.) This idea of a hierarchy is also in keeping with the idea of the literacy of a program - how many of you would prefer a book with only paragraphs and rare chapters as opposed to everything down to paragraph marks? Okay, next programming philosophy, I never use unnamed sections - I find doing so counterproductive. The table of contents produced by spider has the module names indented according to their level in the program hierarchy, making it easy to work out what needs to be done next, what's missing, the significance of a bit of code, etc. And now my final piece of programming philosophy, I always include some description of the code in a section. This makes maintenance easier, and enhances the overall readability of a program. Now, given my programming philosophy, it should become apparent that using an unnamed section with no description is a big no-no for me, which is why I would prefer to be able to have multiple sections of code in a section. Anyhow, I'm probably beginning to babble, so I'll wind up here with a suggestion: either way, the current behaviour of weave should be ammended to either complain about multiple @<---@>= in a section, or to weave/tangle it as I have suggested. Votes? I'd like to hear the opinions of those who maintain WEB tools as the decision effectively remains up to them :-) cheers -steve ================================================================================ Archive-Date: Thu, 07 Jan 1993 19:58:32 CST Date: Fri, 8 Jan 93 01:28:49 GMT From: mfy@sli.com (Mike Yoder) Reply-To: LitProg@SHSU.edu Message-ID: <9301080128.AA02245@ravel.sli.com> To: LitProg@SHSU.edu Subject: benefits of Literate Programming My experience with Literate Programming has given me a different slant on the issue than most people have; I think the principal benefit is not so much that you get good documentation (you don't always) but that you get correct documentation. I don't mean user manuals, which are generally correct but irritatingly ambiguous due to the nature of natural languages: I am referring to documents that purport to describe what a program's data structures and algorithms are. Without LP, my experience says that for programs longer than, say, ten pages of code, the odds that such a document will be correct are zero. I'm not being ironic or exaggerating: I have literally never seen documentation in such cases that was useful. In most cases, either the documentation was written before the program was (and never updated), or it was written just afterward and a very incomplete job was done. I particularly remember one document describing a compiler IL that had quite correct detail about the tree portion of the IL, but was sketchy on the leaf nodes and had virtually nothing on the symbol table. It isn't all that helpful to be told that the tree node representing binary plus has two sons; you could have surmised that. But this was the easiest part of the documentation to write, and the writer was probably under heavy time pressure and trying to get as much down as possible. It is possible, of course, to work with the program directly, but this changes maintenance from a science to an art. This is not intrinsically bad, unless human lives are involved. But in any large program where no "big picture" exists, fixing a bug consists of finding a likely-looking spot and changing it to what feels right in the hopes that it *is* right. If it doesn't work, you repeat the process. It would be better to *know* that such-and-such a routine is supposed to deal with all comments, or macro expansions, or whatever, because this can reduce the amount of code you must examine by an order of magnitude or more. Documents get out of date because they are separated from the source, and so producing them in addition to the program becomes a two-pass process. Besides this, the documentation need not have any obvious 1-1 relationship to the program; so it may be a nontrivial task just to determine what parts of the documentation need to change after the program is modified. No wonder that most programmers take the easy way out and put off fixing the documentation forever. Why literate programming fixes this is partly obvious and partly due to psychological effects I do not claim to understand. It should be clear, though, that when the documentation you must change is at most an editor screen or so away from your program text, there is much less of a psychological barrier to your changing it at the same time as the program. There is one other obvious reason that LP helps: it makes the documentation and program be done at the same time. Once the program works, very few managers *or* programmers are all that keen on spending several weeks producing quality documentation; there's always other ways to spend this time that look more attractive--such as doing firefighting on the project that's behind. Michael F. Yoder [mfy@sli.com] ================================================================================ Archive-Date: Fri, 08 Jan 1993 15:08:56 CST Message-ID: <9301082102.AA11423@im4u.cs.utexas.edu> From: leew@cs.utexas.edu (Lee Wittenberg) Reply-To: LitProg@SHSU.edu Date: Fri, 8 Jan 1993 15:02:53 -0600 To: LitProg@shsu.edu Subject: Re: Defining multiple modules (sections) in one Another point to add to the growing discussion: It's a lot harder for WEB to parse multiple section definitions together than to insist on separate sections separated by @*'s and @ 's. There's no way to tell (until the = is reached) whether it's looking at a section definition or use. Also, what will WEB do with: x = @ = 0; or if (@ == 18) or other similar examples? Both of these (slightly contrived, but similar to code I have seen) would tangle _and_ weave to something unintended if we allow multiple code definitions in a section. NOWEB deals with this problem by requiring section definitions to start at the beginning of a line. It's really too late to require something like that of WEB, CWEB, and the other tools that ignore spaces. -- Lee ================================================================================ Archive-Date: Fri, 08 Jan 1993 15:15:34 CST Message-ID: <9301082112.AA12344@im4u.cs.utexas.edu> From: leew@cs.utexas.edu (Lee Wittenberg) Reply-To: LitProg@SHSU.edu Date: Fri, 8 Jan 1993 15:12:22 -0600 To: LitProg@shsu.edu Subject: Re: bad CWEB formatting ? Denis R. writes: > Somewhere, I use a declaration like > > char line[100]; > > Ctangle gives me a correct C source that compiles without harm. > However, Cweave formats me line as if it was a type, and you can imagine > that the function where line is declared looks bad... > > Of course, I know that line is defined in C (K&R), but the word is not > reserved. So, why does Cweave not understand ? Is there an other > solution than changing the name of my string ? CWEAVE treats a number of non-reserved words (like line, ifdef, NULL) as if they were reserved for simplicity. Most C programmers do not redefine these in their programs. "line" is a bit of a problem, though. It is a natural for variable names. The way around this problem is with the following WEB code in the definition part of a section (assuming that you never use a #line directive in your code): @f line x This will treat "line" as if it were an identifier, which is what you want. It also has the added advantage of documenting the fact that you are using a standard identifier in a non-standard way. Hope this helps. -- Lee ================================================================================ Archive-Date: Fri, 08 Jan 1993 17:41:11 CST Date: Fri, 8 Jan 93 15:27:16 PST From: gcrc!spinosaj@riscsm.scripps.edu (John Spinosa/MS219 4-9937) Reply-To: LitProg@SHSU.edu Message-ID: <9301082327.AA12679@gcrc.scripps.edu> To: litprog@shsu.edu Subject: faq existence? Is there an faq available concerning the different flavors of web (ie, spidery web, cweb, etc) and what systems that they run on? Also, is there some sort of intro paper, book, etc. about literate programming for a novice such as myself? I'll summarize any the responses that I receive. Thanks in advance John Spinosa spinosaj@riscsm.scripps.edu ================================================================================ Archive-Date: Fri, 08 Jan 1993 19:28:11 CST From: Timothy Murphy Reply-To: LitProg@SHSU.edu Subject: Brief communication from a bigot To: LitProg@shsu.edu Date: Sat, 9 Jan 93 1:26:33 GMT Sender: tim@maths.tcd.ie Message-ID: <9301090126.aa23319@salmon.maths.tcd.ie> I believe in C++. I believe in LaTeX. It has been revealed to me that I am right. (It's such a relief to be certain about everything.) It follows that the only True Web is CWEB++ producing LaTeX rather than TeX. Unless Literate Programmers see the light, WEB will be utterly swept away, and entropy will at last attain its maximum. Timothy Murphy e-mail: tim@maths.tcd.ie tel: +353-1-2842366 (home/office) +353-1-7021507 (university) fax: +353-1-2842295 s-mail: School of Mathematics, Trinity College, Dublin 2, Ireland ================================================================================ Archive-Date: Fri, 08 Jan 1993 22:48:24 CST Date: Fri, 8 Jan 93 22:40:48 -0600 From: plyon@emx.cc.utexas.edu (Paul Lyon) Reply-To: LitProg@SHSU.edu Message-ID: <9301090440.AA09918@emx.cc.utexas.edu> To: LitProg@SHSU.edu CC: LitProg@shsu.edu Subject: Brief communication from a bigot Timothy Murphy writes: > It follows that the only True Web is CWEB++ > producing LaTeX rather than TeX. Actually it would have to be a gcc-web, using plain TeX, augmented with something along the lines of Karl Berry's eplain package, together with, say, PiCTeX, and maybe the table macros from TeXsis, as well as any other useful bits that come to mind... Then again, Fweb does do C++, and works with LaTex, so perhaps Murphy's millenium is almost here... Ciao, Paul Lyon ================================================================================ Archive-Date: Fri, 08 Jan 1993 22:49:45 CST Date: Fri, 8 Jan 93 22:40:48 -0600 From: plyon@emx.cc.utexas.edu (Paul Lyon) Reply-To: LitProg@SHSU.edu Message-ID: <9301090440.AA09918@emx.cc.utexas.edu> To: LitProg@SHSU.edu CC: LitProg@shsu.edu Subject: Brief communication from a bigot Timothy Murphy writes: > It follows that the only True Web is CWEB++ > producing LaTeX rather than TeX. Actually it would have to be a gcc-web, using plain TeX, augmented with something along the lines of Karl Berry's eplain package, together with, say, PiCTeX, and maybe the table macros from TeXsis, as well as any other useful bits that come to mind... Then again, Fweb does do C++, and works with LaTex, so perhaps Murphy's millenium is almost here... Ciao, Paul Lyon ================================================================================ Archive-Date: Fri, 08 Jan 1993 22:52:28 CST Date: Fri, 8 Jan 93 22:27:15 -0600 From: plyon@emx.cc.utexas.edu (Paul Lyon) Reply-To: LitProg@SHSU.edu Message-ID: <9301090427.AA10488@emx.cc.utexas.edu> To: LitProg@SHSU.edu CC: LitProg@shsu.edu Subject: Defining multiple modules (sections) in one Lee Wittenberg writes: > NOWEB deals with this problem by requiring section definitions to start at > the beginning of a line. It's really too late to require something like > that of WEB, CWEB, and the other tools that ignore spaces. A better way of dealing with this is the method adopted in Ross William's FunnelWeb programme. There are two parts to it. The first is to require that code sections be enclosed in an explicit pair of delimiters, namely an opening `@{' and a closing `@}', and the second is the requirement that any code section definition must begin with one of two directives, either `@$' (an ordinary section definition) or `@O' (a section defining an output file). Thus, a code section definition looks like this: @$@==@{ ..... code .... @} If the code section may be unused, one puts `@>@Z==@{' at the end instead of `@>==@{' (otherwise the programme complains about a section defined but not used, and this does count as a syntax error), and if it is to be invoked more than once, one puts `@>@M==@{' in place of `@>==@{', lest FunnelWeb refuse to tangle or weave it. Finally, if the section is to be incrementally defined one writes `+=@{' in place of `==@{', and it is deemed an error to mix the two. None of the options apply to output file definitions; these cannot be incrementally defined, nor, sensibly enough, can one use the `@M' modifier. So it will look like this: @O@==@{ #ifdef _MY_HEADER_H #define _MY_HEADER_H 1 .... the contents .... #endif @} Here, of course, the contents will mostly be code section invocations for the function prototypes, data structures or class definitions, and so on. Now such definitions are definitely harder to type, and Funnelweb's fussiness about the syntax is a nuisance, at least at first, but it does allow multiple section definitions following explanatory text, and thus a more free form source file, and the tighter error checking does cut down somewhat on errors in writing the source. The major disadvantage I see is related to the one mentioned by Bart Childs, namely that allowing multiple code sections together with one TeX section complicates the indexing of identifiers, both in terms of the programming but, more importantly, in terms of the ease of finding things using the index entries. This is not an issue in FunnelWeb as it stands, because it is not language specific, so there is no provision for identifier indexing. It would, however, be a problem if one attempted to adapt the FunnelWeb scheme to a Web system with a pretty printing parser of the kind in Cweb, Spiderweb, or Fweb. For, we break the relationship between the numbering of the Web sections (a stretch of exposition followed by one or more code sections) and the numbering of the code sections. Now Williams dealt with this by the simple expedient of not numbering the explanatory text at all; only the code sections bear numbers, and they are only cross-referenced for definition and use with respect to each other. The organization of the exposition is entrusted to a hierarchy of section headings which get ``mil spec'' numbering ('1.2.1' for a sub-sub-heading, for example). But if we do have an identifier (and ``control text'') index, and we allow, as seems proper, that an index entry can reference occurrences in the expository text (as `|identifier|' or by an explicit `@^', `@.' or `@:' directive for control text) as well as ones in the code, then we will need somehow to be able to direct the reader to the proper place. But if text passage number 33 is associated with code sections numbered 49--51, there is still apt to be confusion, even if we find a typographically satisfactory way to distinguish a text passage reference from a code section reference (say `T33' versus `C50' for one unimaginative approach that might nonetheless work). Further, I am assuming that we index things in macro definitions by reference to the text passage immediately preceeding, but I suppose we could always add a third number scheme... (Or, bite the bullet and convert to page number index entries rather than section numbers for some or all of this.) [Aside, in FunnelWeb, there is no difference between macros and code sections: ``code section'' names can have parameter lists. The syntax is clumsy at best, and I have found little use for it. Williams made many sensible design decisions, but I would not number this one among them.] For my part, I think the complexities of the indexing scheme are not a decisive objection, but I suspect others will not agree. Ciao, Paul Lyon ================================================================================ Archive-Date: Fri, 08 Jan 1993 22:53:14 CST Date: Fri, 8 Jan 93 22:27:15 -0600 From: plyon@emx.cc.utexas.edu (Paul Lyon) Reply-To: LitProg@SHSU.edu Message-ID: <9301090427.AA10488@emx.cc.utexas.edu> To: LitProg@SHSU.edu CC: LitProg@shsu.edu Subject: Defining multiple modules (sections) in one Lee Wittenberg writes: > NOWEB deals with this problem by requiring section definitions to start at > the beginning of a line. It's really too late to require something like > that of WEB, CWEB, and the other tools that ignore spaces. A better way of dealing with this is the method adopted in Ross William's FunnelWeb programme. There are two parts to it. The first is to require that code sections be enclosed in an explicit pair of delimiters, namely an opening `@{' and a closing `@}', and the second is the requirement that any code section definition must begin with one of two directives, either `@$' (an ordinary section definition) or `@O' (a section defining an output file). Thus, a code section definition looks like this: @$@==@{ ..... code .... @} If the code section may be unused, one puts `@>@Z==@{' at the end instead of `@>==@{' (otherwise the programme complains about a section defined but not used, and this does count as a syntax error), and if it is to be invoked more than once, one puts `@>@M==@{' in place of `@>==@{', lest FunnelWeb refuse to tangle or weave it. Finally, if the section is to be incrementally defined one writes `+=@{' in place of `==@{', and it is deemed an error to mix the two. None of the options apply to output file definitions; these cannot be incrementally defined, nor, sensibly enough, can one use the `@M' modifier. So it will look like this: @O@==@{ #ifdef _MY_HEADER_H #define _MY_HEADER_H 1 .... the contents .... #endif @} Here, of course, the contents will mostly be code section invocations for the function prototypes, data structures or class definitions, and so on. Now such definitions are definitely harder to type, and Funnelweb's fussiness about the syntax is a nuisance, at least at first, but it does allow multiple section definitions following explanatory text, and thus a more free form source file, and the tighter error checking does cut down somewhat on errors in writing the source. The major disadvantage I see is related to the one mentioned by Bart Childs, namely that allowing multiple code sections together with one TeX section complicates the indexing of identifiers, both in terms of the programming but, more importantly, in terms of the ease of finding things using the index entries. This is not an issue in FunnelWeb as it stands, because it is not language specific, so there is no provision for identifier indexing. It would, however, be a problem if one attempted to adapt the FunnelWeb scheme to a Web system with a pretty printing parser of the kind in Cweb, Spiderweb, or Fweb. For, we break the relationship between the numbering of the Web sections (a stretch of exposition followed by one or more code sections) and the numbering of the code sections. Now Williams dealt with this by the simple expedient of not numbering the explanatory text at all; only the code sections bear numbers, and they are only cross-referenced for definition and use with respect to each other. The organization of the exposition is entrusted to a hierarchy of section headings which get ``mil spec'' numbering ('1.2.1' for a sub-sub-heading, for example). But if we do have an identifier (and ``control text'') index, and we allow, as seems proper, that an index entry can reference occurrences in the expository text (as `|identifier|' or by an explicit `@^', `@.' or `@:' directive for control text) as well as ones in the code, then we will need somehow to be able to direct the reader to the proper place. But if text passage number 33 is associated with code sections numbered 49--51, there is still apt to be confusion, even if we find a typographically satisfactory way to distinguish a text passage reference from a code section reference (say `T33' versus `C50' for one unimaginative approach that might nonetheless work). Further, I am assuming that we index things in macro definitions by reference to the text passage immediately preceeding, but I suppose we could always add a third number scheme... (Or, bite the bullet and convert to page number index entries rather than section numbers for some or all of this.) [Aside, in FunnelWeb, there is no difference between macros and code sections: ``code section'' names can have parameter lists. The syntax is clumsy at best, and I have found little use for it. Williams made many sensible design decisions, but I would not number this one among them.] For my part, I think the complexities of the indexing scheme are not a decisive objection, but I suspect others will not agree. Ciao, Paul Lyon ================================================================================ Archive-Date: Sat, 09 Jan 1993 04:12:23 CST Date: Sat, 9 Jan 93 11:11:43 +0100 From: marcus@x4u.desy.de (Marcus Speh) Reply-To: LitProg@SHSU.edu Message-ID: <9301091011.AA26909@x4u.desy.de> To: LitProg@SHSU.edu Subject: faq existence? References: <9301082327.AA12679@gcrc.scripps.edu> >>>>> On Fri, 8 Jan 93 15:27:16 PST, (John Spinosa/MS219 4-9937) said: > Is there an faq available concerning the different flavors of web (ie, > spidery web, cweb, etc) and what systems that they run on? Also, is > there some sort of intro paper, book, etc. about literate programming for > a novice such as myself? I'll summarize any the responses that I receive. There is justified hope that the upcoming General FAQ for LitProg (not expected before February) will collect related information and provide pointers to other sources of information (care to comment, David?). The other existing FAQ for LitProg for FWEB (which inspite of its name is not a WEB for Fortran only, but also for ratfor, C, C++, TeX, running on a variety of systems, from a PC to the CRAY) gives a pointer to CWEB vs. FWEB (this will be merged into the FAQ for the 03-92 issue) and reflects a discussion on Funnelweb vs. FWEB (based on a posting by Paul Lyon). I will post a detailed announcement and the fweb-faq's text version next week -- please wait (GDG: got my mail?). And who's volunteering for the CWEB FAQ ? The longer you wait, the harder it will be to scan the wealth of information buried deep in LitProg's archives, IMO. --Marcus Speh -- ================================================================================ Archive-Date: Sun, 10 Jan 1993 15:44:38 CST Date: Sun, 10 Jan 93 21:40:41 GMT From: Klaus Elsbernd Reply-To: LitProg@SHSU.edu To: LitProg@shsu.edu Subject: Re: bad CWEB formatting ? Message-ID: <9301102140.aa02189@serv-301.dfki.uni-kl.de> Lee Wittenberg writes: > > Somewhere, I use a declaration like > > > > char line[100]; > > > > Ctangle gives me a correct C source that compiles without harm. > > However, Cweave formats me line as if it was a type, and you can imagine > > that the function where line is declared looks bad... > > > > Of course, I know that line is defined in C (K&R), but the word is not > > reserved. So, why does Cweave not understand ? Is there an other > > solution than changing the name of my string ? > >CWEAVE treats a number of non-reserved words (like line, ifdef, NULL) as if >they were reserved for simplicity. Most C programmers do not redefine >these in their programs. "line" is a bit of a problem, though. It is a >natural for variable names. The way around this problem is with the >following WEB code in the definition part of a section (assuming that you >never use a #line directive in your code): > > @f line x > >This will treat "line" as if it were an identifier, which is what you want. >It also has the added advantage of documenting the fact that you are using >a standard identifier in a non-standard way. > This mentioned problem is not only true if you use non-reserved words like |line| as identifiers. I detected this problem in the following code fragment too: @= struct g_process { int socket; struct msgh *msgh; char *buf; char owner[10]; /* user-id des Benutzers */ time_t connect_time; time_t access_time; time_t give_ivory_time; #ifdef DAEMON Board *p_board; /* ein zum \gproc-Proze\"s geh\"orendes board */ struct g_process *next_g_process; #else int pid; /* process-id of a called process executing genera */ #endif /* DAEMON */ }; typedef struct g_process G_Process; The code formats to = struct g_process {int socket; struct msg *msgh; ... #ifdef DAEMON ... #endif }; typedef struct g_process G_Process; The solution is the same; I inserted @f G_Process int and CWEAVE did the right thing (insert a newline after the structure definition). I hope I made it right and served not the symptom. MfG Klaus Elsbernd ================================================================================ Archive-Date: Sun, 10 Jan 1993 23:24:43 CST Message-ID: <199301110520.AA17584@mucket.vast.unsw.edu.au> To: LitProg@SHSU.edu Subject: Re: Defining multiple modules (sections) in one Date: Mon, 11 Jan 93 16:20:52 +1100 From: stevea@vast.unsw.edu.au Reply-To: LitProg@SHSU.edu leew@cs.utexas.edu (Lee Wittenberg) sez: leew> Another point to add to the growing discussion: It's a lot leew> harder for WEB to parse multiple section definitions together leew> than to insist on separate sections separated by @*'s and @ 's. leew> There's no way to tell (until the = is reached) whether it's leew> looking at a section definition or use. Also, what will WEB do leew> with: leew> x = @ = 0; Okay, my two bits worth (again) - this is not a very good example of literate programming (imho of course). I was under the impression that this sort of code is best handled by the @d mechanism which web provides. I would even be quite suprised if weave was able to handle this sort of code, as I am sure it would have difficulty parsing a section which did not contain complete statements. leew> NOWEB deals with this problem by requiring section definitions leew> to start at the beginning of a line. It's really too late to leew> require something like that of WEB, CWEB, and the other tools leew> that ignore spaces. I'm sure there's a way to do it if we know that @>= ALWAYS means you are defining the code in a new section. cheers -steve ================================================================================ Archive-Date: Sun, 10 Jan 1993 23:43:13 CST Message-ID: <199301110538.AA17599@mucket.vast.unsw.edu.au> To: LitProg@SHSU.edu Subject: Re: Defining multiple modules (sections) in one Date: Mon, 11 Jan 93 16:38:02 +1100 From: stevea@vast.unsw.edu.au Reply-To: LitProg@SHSU.edu Hi all, Paul Lyon brings up a good point (which he attributes to Bart Childs), which I must of missed some how, and that is about the problem with indexing. This is obviously a fairly big problem, seeing as without a sensible indexing scheme, maintenance of a WEB would soon become an impossibility. However, I believe it is one that may be readily solved. If it is made clear that having two code sections in one TeX section is to be an exception rather than the rule, some sort of scheme where the index numbers become 13a and 13b for section 13 could be used. This is a fairly easy index to use (although it might be a pain to generate in a one pass system), and saves the ugly T13, C24 type idea (although this would also work). I don't like the idea of a purely page oriented scheme for the index (although it would make it easier to find the page in a hurry, it may be difficult to find the piece of code), and reckon that my proposed scheme would not separate the notion of code and text. I'm sure everyone is familiar with this sort of scheme for citations (how many people have multiple Knuth citations from the same year in their bibliographies :-)), and is fairly intuitive. Of course, if it is decided to limit one code section to ever TeX section, then the problem disappears pretty quick :-) cheers -steve ================================================================================ Archive-Date: Mon, 11 Jan 1993 04:10:01 CST Date: Mon, 11 Jan 93 11:04:43 +0100 From: marcus@x4u.desy.de (Marcus Speh) Reply-To: LitProg@SHSU.edu Message-ID: <9301111004.AA09119@x4u.desy.de> To: Literate Programmers Subject: Announcement: fweb-faq [01-93] updated CC: Eve Kovacs , Joe Pasciak , Rossen Parashkevov , "Robert G. Edwards" , "Alan D. Sokal" , Burkhard Burow , Maarten Frederik Laes Golterman , "John A. Krommes" , Karsten Kuenne , Marcus Speh ///////////////////////////////////////////////////////////////// Another issue of the LitProg FAQ for FWEB is finished. Its text version will follow in a separate posting to LitProg. How to get the fweb-faq file(s): -------------------------------- Retrieve them via anonymous FTP from the following sites Name: niord.shsu.edu [official FWEB FAQ host] Address: 192.92.115.8 Directory: [FILESERV.FWEB] Name: verdi.imada.ou.dk Address: 129.142.128.14 Directory: pub/faq Name: ftp.uni-stuttgart.de Address: 130.83.55.75 Directory: pub/soft/tex/web/fweb/FAQ Name: lyman.pppl.gov [official FWEB host] Address: 192.55.106.129 Directory: pub/fweb/faq To retrieve the (text) file via e-mail, include: SENDME FAQ.FWEB in the body of a mail message to FILESERV@SHSU.BITNET (FILESERV@SHSU.edu). To retrieve the full family of files (< 500 KByte), include SENDME FAQ.FWEB* instead. [At Niord and Verdi, it may take another day or two to get the files installed.] Changes for this issue of the fweb-faq: --------------------------------------- FWEB-related [and some general] postings from October--December 1992 were used for this update. The form of the fweb-faq changed in several respects. The principal source file is still written in Texinfo. The distribution now has a very simple Makefile for processing that source. I added version 2.90 of the macro file "texinfo.tex" which allows you to run plain TeX on the Texinfo source to obtain a DVI file (without index). A DVI file and a Postscript file (with index) are still included to satisfy everybody's needs. [Texinfo.tex can be retrieved from FILESERV as well--- GDG will tell you how, I assume.] For more details, please look into the file "README.fweb-faq" and the Makefile of the distribution. Mainly as a result of the confusion which arose on the list after a premature discussion on the form of the FAQ file (my fault), I tried to improve on the description. Some Texinfo errors were corrected as well. The total size of the distribution is about 500 KBytes. Not because the FAQ is that big, but because of the support for different versions. If you think that is bad, flame me. I do find Texinfo a most convenient tool for the needs of a maximum number of readers---and I enjoy using it. Please note that a General LitProg FAQ by David B. Thompson is being worked on, thus reducing the the size of the fweb-faq. If possible, we will alternate with updates of these two faqs in intervals of 2--3 months. Related items were marked accordingly. Future FAQ author... -------------------- ...If you want to use "fweb-faq.texi" as a template for your own principal FAQ source file, please do so. I would also like to hear about your experiences, in that case. Another FAQ for CWEB seems highly desirable, considering the relatively poor documentation (the FWEB User's Manual is so complete that it doesn't really need a FAQ, in FAQt). Also, the longer you wait volunteering for it, the harder it will be to scan the wealth of information buried deep in LitProg's archive files, IMO. Thanks to... ------------ ...many readers whose suggestions were very helpful. I am especially grateful to John Krommes [designer of FWEB] for checking the final draft of the faq list, and to Bart Childs [co-designer and maintainer of the Emacs web-mode] for detailed comments on the previous issue and a pre-release of GNU Emacs' web-mode version 1.61. Thanks also to George Greenwade ["GDG", maintainer of FILESERV and LitProg] for support in all stages of the project. All kinds of comments, flames, suggestions will be appreciated. I hope you'll enjoy reading, --Marcus Speh -- //////////////////////////////////////////////////////////////// // marcus@x4u.desy.de // Marcus Speh // // [131.169.30.33] // II. Institut f. Theor. Physik // // Phone: (040)8998-2260 // Luruper Chaussee 149 // // FAX: (040)8998-2267 // 2000 Hamburg 50 / Germany // //////////////////////////////////////////////////////////////// ================================================================================ Archive-Date: Mon, 11 Jan 1993 04:14:09 CST Date: Mon, 11 Jan 93 11:10:47 +0100 From: marcus@x4u.desy.de (Marcus Speh) Reply-To: LitProg@SHSU.edu Message-ID: <9301111010.AA10754@x4u.desy.de> To: Literate Programmers CC: Marcus Speh Subject: fweb faq list [01-93]---text version This is text file `fweb-faq', produced by GNU Makeinfo-1.49 from the Texinfo file `fweb-faq.texi'. >> To see the questions, display lines matching the regexp "^\[[1-9]" << >> To see the index, display lines matching the regexp "^\* " << >> To see a related question, follow the reference after "*note...:" << ///////////////////////////////////////////////////////////////////// // FWEB in Questions and Answers (01/93) // ///////////////////////////////////////////////////////////////////// [last updated 5 Jan 1993] [Send comments to: Marcus Speh, marcus@x4u.desy.de] This article contains frequently asked questions and their answers concerning the FWEB system of "Literate Programming" from the "LitProg" mailing list, until January 1993. Most of the answers are taken from the postings, with little moderation from my side. The original postings are archived at `niord.shsu.edu' in directory `[FILESERV.LITPROG]'. Comments, corrections and suggestions from several people were used to improve single questions and answers (*note Acknowledgements::.). Most notably, John Krommes, FWEB's designer, provided a wealth of useful comments. I have dubbed him "JAK" in some places. Inside quotes, my own comments are marked "[... -MS]". Sections of the FWEB User's Manual are referred to by their section numbers, as in "[M-10.2]" (*note What is the difference between the FAQ and the manual?: Question 5.). Introduction and Editorial *************************** [1] What is FWEB? ================== For a thorough discussion of the WEB system, I refer to the extensive literature, collected in Nelson Beebe's bibliography (at `ftp.math.utah.edu' in directory `pub/tex/bib'). For pointers, see the upcoming "General FAQ" by Dave Thompson. The WEB system. --------------- In D.E. Knuth's [author of the original WEB, coauthor of CWEB] own words, [M-2.4] "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 (1) 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." FWEB - a multilingual WEB variant. ---------------------------------- FWEB which is being supported and upgraded by John Krommes is a substantial extension of CWEB, FWEB supports C, C++, Fortran, Fortran90, Ratfor, and TeX i.e. writing TeX macros (style files). It runs on most platforms: VMS, PC, UNIX, and pretty much anything that the GNU C compiler (GCC) is supported for. JAK [M-1]: "The principal design contributions to this version of WEB are 1. the concept of a current language, so that one can process code written in multiple languages in the same WEB run; 2. new production rules for Fortran, Ratfor, and TeX (and some modifications of Levy's (2) rules for C; 3. a C-like built-in macro preprocessor; 4. the ability to directly translate Ratfor into Fortran. In addition, many miscellaneous details have been changed and a variety of convenience features has been added." ---------- Footnotes ---------- (1) [which itself is written in Knuth's original Pascal WEB -MS] (2) [Levy and Knuth are the authors of the C variant of WEB -MS] [2] How can I subscribe to LitProg? ==================================== If you are not yet subscribed to LitProg, but you are interested, send a MAIL message to `LISTSERV@SHSU.BITNET, or listserv@shsu.edu, or LitProg-Request@shsu.edu' stating in the text of the MAIL: `SUBSCRIBE LITPROG your name in quotes'. The list itself is unmoderated: messages sent to `litprog@shsu.edu' are automatically distributed to all subscribers. [3] How can I get the FWEB FAQ? ================================ You may obtain the latest version of this FAQ via anonymous FTP from - `niord.shsu.edu' [192.92.115.8] in directory `[FILESERV.FWEB]', - `lyman.pppl.gov' [192.55.106.129] in directory `/pub/fweb/faq', - `ftp.imada.ou.dk' [129.142.128.14] in directory `/pub/faq', and `ftp.uni-stuttgart.de' [130.83.55.75] in directory `pub/soft/tex/web/fweb/FAQ'. To retrieve the plain text file via e-mail, include SENDME FAQ.FWEB in the body of a mail message to FILESERV@SHSU.BITNET (fileserv@shsu.edu). Send the command SENDME FILELIST in a mail message to `FILESERV' to get valid information on the names of the downloaded files if you'd like to have another version of the fweb-faq (*note Which versions of the FAQ are available?: Question 4.). NOTE: do *not* include the message `SENDME FWEB' unless you want the full FWEB distribution! [4] Which versions of the FAQ are available? ============================================= Besides the text file `fweb-faq', the FAQ is available as a Texinfo, a PostScript, an Info or a DVI file. All these can be generated from the Texinfo source file `fweb-faq.texi'. The preprocessed DVI and PostScript files are not included anymore. See the simple makefile which accompanies the fweb-faq distribution for detailed information on how to process the Texinfo source. Short instructions are given in the file `README.fweb-faq'. If you do not know anything about Texinfo, don't worry: With the `texinfo.tex' macro package, the principal source file `fweb-faq.texi' can be TeXed (1) like any ordinary TeX file at the expense of not getting an index -- try it! If you would like to start with Texinfo, retrieve its latest version from `prep.ai.mit.edu' in directory `pub/gnu' (*note How can I contribute?: Question 6.). ---------- Footnotes ---------- (1) If you do not have TeX, you may GNU's `texi2roff' for formatting. [5] What is the difference between the FAQ and the manual? =========================================================== Most of the stuff in FAQs *is* in the manual, but people either don't read the manual, or it is too hidden to be found (the FWEB User's Manual currently has more than 200 pages). Thus the FAQ provides, if you will, an index to the manual for those questions that come up regularly. Where possible, sections of the User's Manual for the last release (FWEB version 1.23a) are referred to by their section numbers in square brackets, as in "[M-10.2]". [6] How can I contribute? ========================== If you think that structure or content of this part of the FAQ can be improved, or if you think you have discovered an error, either write to me or post your comment to LitProg (with `fweb-faq (version)' somewhere in the `Subject' line). If you find your name and email adress anywhere on these pages, I'd be grateful if you check whether I got them right and inform me otherwise. The same for errors in ftp site addresses and `Archive-Date' (look into the `Makefile' to learn how to make these visible). "The FAQ" for Literate Programming will probably not exist before the is a unified tool rather than a family of different environments. On LitProg, all these environments are subject to discussion, and a family of FAQ lists is planned, together with a master FAQ list for general questions. This general FAQ will be maintained by David B. Thompson . If you are interested in participating in one of the FAQ lists for LitProg, either contact George D. Greenwade (E-mail: `bed_gdg@shsu.edu' [Internet], `bed_gdg@shsu' [Bitnet], `shsu::bed_gdg' [DECnet]), who maintains LitProg as well as the `FILESERV' repository at Sam Houston State University, or simply announce your wish on the LitProg mailing list. If you want to write a FAQ yourself, get "FAQ writer's FAQ" (by Nathan Torkington and Ian Kluft) which originates from the faq-maintainers mailing list. It can also be obtained via email by including `SENDME FAQ.WRITING' in the body of a mail message to `FILESERV', or retrieved from `niord.shsu.edu' in `[FILESERV.FAQ]FAQ.WRITING'. If you want to write your FAQ list in Texinfo, use `fweb-faq.texi' as a template for the principal source file (*note Which versions of the FAQ are available?: Question 4.). [7] What else should be included in the FAQ? ============================================= * Merge the FAQs from the FWEB User's Manual with this list. * Remove items of more general character in favor of Dave Thompson's general FAQ for LitProg. * Give more details on the form of the FAQ file's Texinfo source? * Add thoughts on OOP using the FWEB system (*note Which WEB shall I use for C++: Question 16.)? * Should I include information on how to use FTP? * Should this or another member of the LitProg FAQ list family be cross-posted to USENET (`comp.text.tex', `news.answers')? Please send me your opinion on these items and suggest more things which should be done! Acknowledgements ================= Thanks to all those whose postings in LitProg I have used and who have sent me corrections, especially Bart Childs, Johannes Muller, David Thompson and Don Petcher for this number of the FAQ, and to Robert Chassell [FSF, GNU Texinfo and Elisp support] for help with some Texinfo bugs. Thanks to the sysadmins who put up the files on FTP sites, especially Thorbjoern Ravn Andersen (ftp.imada.ou.dk) and Joachim Schrod (ftp.th-darmstadt.de). Special thanks to George D. Greenwade for maintaining the list and the file archives at Sam Houston University, and to John Krommes for checking this FAQ list for his child. Personally, I feel indebted to Thorsten Ohl for having introduced me to FWEB in the first place, and having taught me many more things related to computing. FWEB sources/Manual/Installation ********************************* [8] Where can I get FWEB? ========================== You can get FWEB (version 1.23a) via anonymous FTP either from `lyman.pppl.gov', in directory `pub/fweb/v1.23': /anonymous@lyman.pppl.gov:/pub/fweb/v1.23: -rwxr-xr-x 1 4145 589 8396 Apr 14 22:45 INSTALL.FWEB* -rw-r--r-- 1 4145 589 18967 Apr 14 22:45 Makefile -rw-r--r-- 1 4145 589 3068 Apr 14 22:45 READ_ME.FWEB -rw-r--r-- 1 4145 589 94 Apr 14 22:45 TAR.exclude -rw-r--r-- 1 4145 589 1419071 Apr 14 22:45 TAR.v1.23.Z drwxr-sr-x 2 4145 589 512 Apr 14 22:45 demos/ drwxr-sr-x 2 4145 589 1536 Apr 15 18:06 manual/ ... Or from `niord.shsu.edu', in directory `[FILESERV.FWEB]': /anonymous@niord.shsu.edu:/ANON_DEV:/FILESERV/FWEB: FWEB-V1_23.TAR_Z;1 2772 21-JUL-1992 12:28 (RWE,RWED,RE,RE) FWEB-V1_23.ZIP;1 2370 21-JUL-1992 13:10 (RWE,RWED,RE,RE) ... INTRO.PS;1 175 22-JUL-1992 16:52 (RWE,RWED,RE,RE) ... The PostScript file `INTRO.PS' gives a short introduction to Literate Programming in general, combined with a simple Fortran example program in FWEB. Note that there's also a user/syntax reference guide which can be obtained independently of the full manual. If you are a seasoned WEB user, the reference guide should be adequate. [9] What is the latest version of FWEB? ======================================== The latest version of FWEB is 1.23a - some time in January 1993, version 1.30-beta is bound to come out. Versions that are explicitly intended to be beta versions are now indicated as such--e.g., v1.30-beta--in the banner line from the processors. JAK: "However, given the fragmented state of my time, in some sense they're all beta." The latest version can be retrieved via anonymous FTP as described in *Note Where can I get FWEB?: Question 8. [10] Where can I get FWEB for the PC? ====================================== The official FWEB PC executables are generated as part of each FWEB release. Retrieve them from the FWEB distribution site `lyman.pppl.gov' (*note Where can I get FWEB?: Question 8.) buried deep down in `pub/fweb/v1.23/boot/ibm/pc': ... 312 -rw-r--r-x 1 4145 589 304636 Apr 15 1992 ftangle.exe* 272 -rw-r--r-x 1 4145 589 268878 Apr 15 1992 ftangle0.exe* 280 -rw-r--r-x 1 4145 589 277032 Apr 15 1992 fweave.exe* ... `ftangle0.exe' is ftangle without the Ratfor preprocessor (*note Why is FWEB so huge?: Question 26.). Hans-Hermann Bode announced his precompiled files for the PC. They can be retrieved from `anonymous@niord.shsu.edu:[FILESERV.PC-WEB]': 00INDEX.;1 2 23-JUL-1992 16:26:54.85 ... FWEBEXE.README;1 6 11-JUN-1992 00:15:18.00 FWEBEXE.READ_ME;1 42 9-JUN-1992 12:13:34.00 FWEBEXE.ZIP;1 1525 23-JUL-1992 16:06:33.26 FWEBEXE.ZIP-LST;1 2 23-JUL-1992 16:22:24.54 ... or in Europe from `dione.rz.uni-osnabrueck.de' (in directory: `pub/msdos/tex/web'), and from `ftp.uni-stuttgart' (in directory `soft/tex/web/cweb'). [11] Is FWEB small enough to compile on a PC? ============================================== Yes. It is known to compile with MicroSoft C 6.00 and Turbo C. JAK: "As a remark, it took some considerable pain to make this work. The larger sources, such as `ftangle.web', had to be split into as many as 3 parts (handled by WEB macros and module names). The make file compiles each of those parts separately, then combines them at link stage. Before this was done, compilers tended to bomb with messages such as `Out of heap space'." On LitProg, Tero Laakkonen reported that FWEB also compiles under linux-096c with gcc-2.2.2 on a 80386. In general, John Krommes offers support for porting FWEB to new systems - contact . [12] Has anyone installed FWEB on an HP machine? ================================================= Either get GCC (the GNU C Compiler), or use (if you have it) the unbundled Hewlett-Packard ANSI C Compiler, which is invoked with `cc -Aa -D _HPUX_SOURCE' (as `cc(1)' explains in detail). Then `make' should proceed without any problems. Common Things People Want To Know ********************************** [13] Can I use LaTeX with FWEB? ================================ In principle, you may use any package of TeX macros you like. However, an arbitrary macro package may contain conflicts with macros used in `fwebmac.sty'. Such conflicts are supposed to be eliminated for LaTeX). As for LaTeX which is probably the package most widely used, you have to do two things at minimum [M-19.7.22]: 1. Use the command-line option `-PL' (or place them into your initialization file `~/.fweb' (*note Key differences for FWEB on different systems?: Question 25.). 2. Process fweave's output with `latex' instead of `tex'. In most cases, to use LaTeX with FWEB it suffices to just say `latex test' instead of `tex test'. (I.e., an attempt is made to hide internally whatever differences there are.) It never hurts, and sometimes helps, to use the command-line option `-PL' (select post-processor LaTeX). To print a `|' in a `verbatim' environment, use `@|', like: `\begin{verbatim} ... @| ... \end{verbatim}'. Since FWEB overrides the `\output' routine of LaTeX, some clever page layout facilities will not work - e.g. there are no floating bodies: while the `table' environment is lost, the `tabular' environment still works. See [M-19.22] for details. Bart Childs reports that the use of AMSTeX causes some problems but that it has been done. Difficulties with using LaTeX should be reported directly to Krommes. For bringing in `lex' and `yacc' scripts and the problem of using LaTeX's `\footnote', *Note Can I use lex and yacc scripts with FWEB?: Question 14. [14] Can I use lex and yacc scripts with FWEB? =============================================== Lewis Perin reported that he has succeeded bringing in `lex' and `yacc' UNIX scripts in for FWEB using LaTeX's `verbatim' environment. [15] Can I use the footnote environment from LaTeX? ==================================================== Lewis Perin reports that the superscripts of `\footnotes' appear in the main text while the actual footnote is nowhere to be seen. In his reply, Zdenek Wagner refers to a style file `ftn.sty' which he wrote to correct this (originally for use with CWEB, it seems). `ftn.sty' can be retrieved from `niord.shsu.edu' [192.92.115.8] in directory `[FILESERV.STY]'. [16] Which WEB shall I use for C++ ? ===================================== As CWEB's coauthor Silvio Levy said, starting from version 2.9 (beta), CWEB will understand C++ syntax as well. Successful compilation on the PC with Borland-C++ was reported on LitProg. In the opinion of many people, FWEB is the best CWEB available. It also supports C, C++, F90, Ratfor, Ratfor-90, and writing TeX macros wherein (f)tangle produces `.sty' files. As for the more general question of Object-Oriented Literate Programming, a very interesting discussion was started by Paul Lyon in December. Hopefully, this topic will make it to Dave Thompson's General FAQ for LitProg (*note How can I contribute?: Question 6.). [17] Does FWEB support Makefiles? ================================== Not yet. This is planned, though [M-10.2]. [18] FWEB with the GNU Emacs editor? ===================================== If you are developing your FWEB programs using the GNU Emacs editor, there is `web-mode.el' by Mark Motl ; the corresponding GNU Emacs "mode" can deal with WEB, CWEB and FWEB. It is capable of many things, including jumping to sections and modules, inserting (and previewing) index entries, hiding and exibiting the body of a `.web' file (showing the tree), inserting, quoting, and consistently renaming modules etc. It supports change files and journal files. It is especially useful when dealing with large `.web' files not to have to deal with "monolithic" FWEB files. For more information, you may obtain a 30pp. User's Manual and the source files from the author, from Bart Childs . The current version of `web-mode' (v 1.61, as of Dec 28, 1992) is faster, more robust, and the documentation in the manual is improved and more accurate now. You may also obtain this version as a 220 KByte shell archive from me . [19] How do I turn off double sided pagination in FWEB? ======================================================== In FWEB, the command `\identicalpageheadstrue' [to be put in the so called "limbo" part of your FWEB file] makes all page headers identical, but it puts the page numbers in the upper LEFT corner and the section numbers in the upper RIGHT corner. As Don Petcher pointed out, to do it the other way around you can either change the macro `\normaloutput' in `fwebmac.sty' as indicated: \def\normaloutput#1#2#3{\shipout\vbox{ \ifodd\pageno\hoffset=\pageshift\fi \vbox to\fullpageheight { \iftitle\global\titlefalse \else\hbox to\pagewidth {\vbox to10pt{}% \ifidenticalpageheads#3\else % THIS WAS ORIGINALLY #2 <--------- \ifodd\pageno #3% Makes page numbers alternate left \& right. \else#2\fi \fi }% \fi \vfill#1 }}% Parameter |#1| is the page itself \global\advance\pageno by1} or you can include the above version in your TeX file as a redefinition of the macro. [20] Can I define (and format) new reserved words? =================================================== Assume you want to declare `far' to indicate a function pointer: void far (*reset)(); In order for fweave to treat `far' like a reserved word in C (or any of the language supported by FWEB), say @f far int somewhere in your source. Weave does not by default recognize `|far|' as a reserved word (this property extends to cweave as well). The formatting with `@f' is *language-specific*; it only applies to identifiers used in the language in force at the point the format statement is encountered. This feature allows a WEB programmer to invent new reserved words and/or to unreserve some reserved identifiers [M-11.12]. [21] Symbolic debugging of FWEB files? ======================================= FWEB inserts sync lines `#line 137 foo.web' into the code, so any compiler/debugger worth its money should respect them. (Including those running under MS-DOS.) Extra FWEB comments in the tangled output can be suppressed by a simple command line switch. See [M-14.2] for a list of command line options. NB: well thought out code needs less time debugging - comments like "since I've started using anyWEB, my debugger has just been collecting dust ..." were reported from many people on the list. [22] Inserting meta-comments in FWEB files? ============================================ Johannes Muller reported strange output from fweave when defining two macros "debug" and "gubed" to enclose optional code for debugging purposes. As his global language, he chose C++. @m debug @( @m gubed @) @f debug do @f gubed while This worked fine for him using WEB with Pascal. `@(' and `@)' are control codes which mark the begin and end of a "meta-comment", i.e. commented out code that will appear in the output file [M-11.38]. Though I wasn't able to reproduce his errors, it should be remarked that the preferred way is to use the WEB preprocessor construction `@#if(0) ... @#endif' instead. JAK: "That Muller's example doesn't work probably points out a problem with the macro preprocessor". For debugging purposes, one can bracket pieces of code by `@#ifdef DEBUG ... @#endif', switching on DEBUG by the commandline flag `-mDEBUG' for ftangle [M-7.5]. [23] Automatic referencing in documentation sections? ====================================================== To produce the woven output For info on porting, see section 5 As Steve Avery reported, you can cheat and, somewhere after you start the module, just throw in something like `\let\refporting=\modno' and then reference it by `see section~\refporting'. In FWEB, `\modno' is set to the number of the module being typeset. Another way to refer to a section is described in [M-19.7.18]: @ Porting. \modlabel{PORTING} ... more ... @ Another section. \modlabel{ANOTHER} For info on Porting, see \WEBsection{PORTING}. `section' is inserted automagically. In the same fashion, the label `ANOTHER' allows the user to refer to that section number. In LaTeX, forward referencing works, in Plain TeX it doesn't. Unless you're using LaTeX, the latter recipe requires that `\modlabel{ANOTHER}' is defined before referring to it. If you want to say "module" instead of "section", use `\WEBmodule' (or equivalently `\module') instead of `\WEBsection'. [24] How do I make a title appear on the contents page? ======================================================== Bart Childs contributed three short files to solve that problem. These listings will disappear here once the full `web-mode.el' distribution (*note FWEB with the GNU Emacs editor?: Question 18.) is available at `FILESERV': * `limbo.material' may be used as the initial skeleton for all WEB files. There is a line containing `\def\title' which should be modified to include the `title'. Also note that the first few lines are to encourage a little more documentation about the source. A few lines further into this is a similar convenience to add an abstract that will appear on the cover page too. * `limbo.sty' is a convenient place to record macros that are commonly used in WEB files. * `time.tex', required by `limbo.material'. Note that the `limbo' style-file parameter can be used to automatically insert common material into the limbo section of an FWEB file. `limbo.material' ----------------- ----------------------- limbo.material ------------------ % % ??????.web, ?fweb version 1.23 % Author % Address % e-mail and phone % % LIMBO MATERIAL % \input limbo.sty \def\title{{\tt }} %% Comment the previous and uncomment this if you don't use web-mode %%\def\title{{\tt ?? I need a Title ??}} %%% begin Bottom of Contents Page macro \def\botofcontents{\vskip 0pt plus 1fil minus 1.5in {\bigskip\parskip6pt plus2pt \parindent20pt %% begin abstract \vskip0.5in \noindent{\bf Abstract. }\it }%% end abstract %% BC often puts this in as a comment about pre-release versions ... %\vskip0.5in %{\vfill\it %% comments on anything else ???? % %\vfil}% end of comments on anything else \vfil \rightline{My Name}% You can personalize your output here, for example. \rightline{\today }% today.tex should be preloaded, input it if not \rightline{\miltime }% time.tex should be preloaded, input it if not }% end of botofcontents % END OF LIMBO MATERIAL % % % BEGINNING OF WEB % %% Delete the next line after appropriate substitution. %% In fweb's you want an @c, @c++, @n, @n9, or @Lx at this point @* First Module. @* Index. `limbo.sty' ------------ ------------------------ limbo.sty ------------------------- % \input today %%%%% How Ridiculous, preload it!!!!!!!!! \font\ninett=cmtt9 \font\ninerm=cmr9 \let\mc=\ninerm % medium caps for names like UNIX \font\Csc=cmcsc10 % Computer Modern Computer Small Caps \def\PASCAL{{\rm Pascal}}% Does very little \def\WEB{{\ninett WEB}}% use like \WEB{} to make space significant \let\web=\WEB \def\FWEB{{\ninett FWEB}} \let\fweb=\FWEB \def\Fortran{{\Csc Fortran}} \def\Cee{{\bf C}} \def\Unix{{\mc UNIX}} \let\unix=\Unix \def\BSl{{\rm\char'134}} \def\<{$\langle\,$} \def\>{$\,\rangle$} % %%% begin Top of Contents Page macro % \def\topofcontents{\hsize 6in \vglue -30pt plus 1fil minus 1.5in \centerline{\title} \vskip 15pt \centerline{\today} \bigskip \vfill \def\?##1]{\hbox to 1in{\hfil##1.\ }}}% end of topofcontents `time.tex' ----------- -------------------------- time.tex ---------------------- \newcount\milhours\newcount\minutes\newcount\hours \def\thetime{\milhours=\time \divide\milhours by 60 \minutes=\milhours \multiply \minutes by -60 \advance\minutes by \time \hours=\time \divide\hours by 60 \ifnum \hours>12 \advance \hours by -12 \fi \the\hours:\ifnum \minutes > 9 \the\minutes \else 0\the\minutes \fi} \def\miltime{\milhours=\time \divide\milhours by 60 \minutes=\milhours \multiply \minutes by -60 \advance\minutes by \time \the\milhours:\ifnum\minutes>9 \the\minutes\else 0\the\minutes \fi} [25] Key differences for FWEB on different systems? ==================================================== The machine dependent files, especially `custom.h' and `defaults.mk' necessary for bootstrapping, can be found in the current distribution of FWEB (v1.23a) in subdirectory `/boot/'. See the `READ_ME.*' files there for details. To run FWEB, commonly used options can be put into an initialization file [M-14.3] (default name `.fweb'). The subdir's of `/boot/' contain sample `.fweb' files with necessary commandline options for the system on which FWEB was built. [26] Why is FWEB so huge? ========================== Most of FWEB's size can be attributed to the need of supporting vastly different languages. The input routines for a free form language are not usable for Fortran and vice versa. Furthermore, FWEB has a Ratfor processor built in (which is a *big* plus, though it is not strictly related to literate programming). JAK: "Two other reasons for the large size are 1. the built-in macro preprocessor, an extended version of that for ANSI C; 2. the style-file mechanism. On the positive side, FWEB does most of its memory allocations dynamically, so one can cut down the size of various tables if necessary. Type `ftangle -Y' to find out about the current allocations; use the `-y' option to change them. The statistics option `-s' is also helpful to find out how much a job actually uses." If you do not want the Ratfor preprocessor, you can make a smaller `ftangle' with the option `LOAD\_RATFOR=0' (see the file `web/ratfor0.web' of the FWEB distribution, and [5]). [27] What is the difference between CWEB and FWEB? =================================================== See [M-19.8], Appendix H, for a short list comparing these two variants of the WEB system. [28] What is the difference between FWEB and Funnelweb? ======================================================== The following was extracted from a text by Paul Lyon (and will eventually be merged with a FAQ for Funnelweb ...): "FWEB and Funnelweb are quite distinct. FWEB is built on top of the CWEB framework; although the parser in its weave processor can do more--all of ratfor, C, C++, and (though the support is not complete), TeX, it is still confined to those specific languages, and still imposes on the user the formatting conventions that please its author. To get something different you will have to hack the weave processor. (One could possibly get somewhere by modifying the TeX macro package that FWEB uses, but that might be the harder way to go, unless, of course, you are already a TeXpert) ... Funnelweb, on the other hand, does not try to parse the "source" code at all; it just takes the layout of the source as written, turns off the meaning of plain TeX special characters, sets typewriter font, and then invokes `\obeylines' and `\obeyspaces'; all this together causes TeX to print the source verbatim (the paragraph formatting is turned off, and TeX does not gobble spaces). The original WEB, CWEB, FWEB, and Spiderweb all parse and format the source, inserting TeX math codes for the operators, putting keywords in boldfont, adjusting the indentation, and so on. If you like the style chosen for the programme, it looks much nicer that way. Except for Spiderweb, which can be adapted to various languages by allowing a fair range of variation in specifying the pretty printing grammar using a large `awk' script to process the grammar spec and generate replacement code for significant chunks of weave, the pretty printing parser(s) in the other are hard coded. This has it uses besides making the typeset code more attractive; WEB, CWEB, FWEB, and Spiderweb all do an index of identifiers for the code that can differentiate, for the most part, between declaration and use of an identifier (they know enough about the grammar to do that, but not, of course, as much as a compiler or interpreter) ..." [Rest deleted: continues with more details on Funnelweb.] JAK: "Don't hack `fweave'! Many effects can be obtained by modifying `fwebmac.sty'. (If one knows enough to hack `fweave', he presumably knows enough to hack `fwebmac.sty' instead.) Note that the style-file mechanism does provide some degree of customization." Please report customizations that are really necessary to John Krommes. [29] Do FWEB files necessarily have to be monolithic? ====================================================== [Later, this item might move to the general FAQ by David B. Thompson] There is no real support for multiple source files under FWEB. What some might like to see is a solution similar to the one presented by Cameron Smith in his `KR-CWEB-SAMPLE' distribution. He had to hack CWEB's `cwebmac.sty' to get a neat table of contents and a combined index distinguishing between entries from different source files [in fact, `KR-CWEB-SAMPLE' illustrates many more things, all more or less related to breaking up a literate C program into multiple source files]. For illustration, this is how the table of contents should look like (sample from Cameron's files): source module 1: main Sect Page introduction..................1.1 1.1 main pgm......................1.4 1.2 index.........................1.10 1.4 source module 2: getop introduction..................2.1 2.1 etc. while entries of the combined index are separated like Index for source module 1: main ... Index for source module 2: getop ... ... Sections in source module 1: main used in section 4... ... For FWEB, the inclusion of files using `@i' is a partial solution [M-11-13] to avoid having to put all the source code in one file. So far, nobody has presented a solution in Cameron's spirit. This feature is put on JAK's list of possible future enhancements. It will not be in c1.30, though. Note that CWEB has got an `@i' option, too (although FWEB's is somewhat more general). Yet another approach (not limited to FWEB) is the use of a "smart" editor like GNU Emacs, combined with a "smart" tool like `web-mode' which is effectively hiding many of the mischiefs of monolithic source files from the programmer. (*note FWEB with the GNU Emacs editor?: Question 18.). [30] How did tangle and weave get their names? =============================================== [Later, this item might move to the general FAQ by David B. Thompson] In a reply, Cameron Smith wrote: "One of the problems with having a single preeminent writer in a language is that everyone always assumes that any enduring tidbit came from his pen ...". Fortunately, for the question "How did tangle and weave get their names", the circulus vitiosus of erroneously quoting William Shakespeare could be broken. The full answer: O, what a tangled web we weave When first we practise to deceive! -- Sir Walter Scott, _Marmion_, canto 6, verse xvii (1808) Cameron also suggested to include these lines by Richard Palais (1982): O, what a tangled WEB we weave When TeX we practise to conceive! Concerning FWEB, JAK reluctantly remarks [M-1]: "We shall call this new version FWEB when necessary ...". And more recently: "I now think the choice of `F' in FWEB was a mistake. `F' stands for Fortran, which motivated this project, but the ability of FWEB to handle multiple languages is one of its most distinctive and useful features. But it's probably too late now." The question to which extent "WEB" inherits from certain German words I'll leave to the native speakers (with a light heart). [31] How am I supposed to abbreviate "Literate Programming"? ============================================================= [Later, this item might move to the general FAQ by David B. Thompson.] There wasn't a clean vote on the mailing list. Most people seemed to agree that one should not misuse common abbreviations like "LP", "LPR" etc. Also, the acronym should be pronounceable (thus eliminating "LitPgm" e.g.). The list's name "LitProg", proposed by Cameron Smith, seems to be accepted by a majority now. This is also the acronym adopted for the FAQ list. General Questions/Bugs/Problems ******************************** [32] What if I think I found a bug in FWEB? ============================================ John Krommes actively supports FWEB -- he must be considered the ultimate source of wisdom. Once you think you've found a bug, put it out on the list. If nobody responds, cut your file down to the smallest subfile that still exhibits the problem you encountered. Then you may contact John. [33] Problem opening a new output file for tangled code? ========================================================= If you're using FWEB's `@o' option in order to open a new output file for tangled code (with local scope - i.e. for the duration of the current section only [M-11.21]), you may see output looking like this: > ftangle test This is ScRaMbLeD FTANGLE [SunOS/UNIX version 1.23a (April 13, 1992)]. Reading test.web ... *1 *4 *6 Writing the output file(s): (test.c)(getop.hQmSWs) Done. CPU = 0.3 sec.; REAL = 0.8 sec. CPU/REAL = 45.0%. [FTANGLE: No errors were found.] with spurious characters in the output file names. This is a bug which will be fixed in FWEB version 1.23b as promised in the `README' file of the FWEB distribution v1.23a. Preliminary Bug Report ...................... Aside the list, Don Petcher reports a more specific version of the problem (this seems to affect both the local `@o' and the global scope command `@O'): If you change output files with the `@O' command (or the `@o' command) and the second filename is shorter than the first, then the second filename gets spurious characters added. E.g. creating `*.cc' files and `*.h' files, the `*.h' file always gets an extra character after the first writing to the `*.cc' file. A temporary cludge is obvious - add an extra character to the `*' part of the `*.h' file. So your file names don't go together well, but you escape the problem. It now seems as if this bug is pretty much machine dependent. The recipe pointed out in the last edition of this list, adding characters to the name part of the secondary output file, only works for Don Petcher on his NeXT workstation. Stirred up by Johannes' complaint Don and I tried a couple of silly programs on his NeXT, on a HP9000, on an Apollo 700, on a Sun-4 and on a Silicon Graphics workstation (SGI). The result was that none of the machines behaves the same for the programs we tried. The Apollo did not exhibit the bug at all, for the NeXT Don's cludge works. The HP accepts output file names "g" and "g." but produces spurious characters for "g.h" - the Sun only accepts "g" but not "g." and "g.h". The SGI exhibits the error if the filename contains more than one underscore or if the filename is longer than six letters. JAK: "I think this is fixed. I will attempt to thoroughly test this out before releasing v1.30." [34] Maximum number of equal characters in different section names? ==================================================================== FWEB may have problems distinguishing section names, if one of them is an exact subset of a longer name rather than a length. This is a bug in the mind of some, but it may as well be regarded a good "feature" as it should be a warning that poor choices of names has happened. JAK: "I think it's a feature, not a bug. And unless I screwed something up, the behavior derives from CWEB." [35] Must I leave leading blanks in my fortran FWEB file? ========================================================== Yes, you should. This is proven by the following example coming from Bart Childs. @n @* The world is not perfect. This wonderfully short problem blows outputs garbage from fweave and ftangle if you don't have the leading six columns blank. Be careful, because in many cases FWEB works fine without the requisite leading blanks. @a program final_exam implicit none integer i, j do i = 1, 7, 2 do j = 6, 1, -1 write(*,*) i, j end do end do end To see the effect on fweave, indent with 4 leading blank spaces instead of 6. JAK: "The input reader for Fortran--77 *follows the rules* of Fortran--77--i.e., statement labels in columns 1--5, continuation character in column 6, columns 6--72 for code. However, note that Ratfor uses free-form syntax, and Fortran--90 also has a free-form syntax mode, which FWEB attempts to support." Index ****** * Menu: * #line: Question 21. * -PL, select pre-processor LaTeX: Question 13. * -s, FWEB statistics option: Question 26. * .fweb: Question 13. * /anonymous@lyman.pppl.gov/pub/fweb/v1.23: Question 8. * /anonymous@niord.shsu.edu/FILESERV/FWEB: Question 8. * @(: Question 22. * @): Question 22. * @f: Question 20. * @O: Question 33. * @o: Question 33. * @|, in LaTeX verbatim: Question 13. * AMSTeX: Question 13. * anonymous FTP: Question 3. * anonymous FTP: Question 8. * anonymous@dione.rz.uni-osnabrueck.de: Question 10. * anonymous@ftp.imada.ou.dk/pub/faq: Question 3. * anonymous@ftp.uni-stuttgart.de: Question 10. * anonymous@ftp.uni-stuttgart.de/pub/soft/tex/web/fweb: Question 3. * anonymous@lyman.pppl.gov: Question 10. * anonymous@niord.shsu.edu/FILESERV/FWEB: Question 3. * anonymous@niord.shsu.edu/[FILESERV.PC-WEB]: Question 10. * ANSI C: Question 12. * Appendix H: Question 27. * Archive-Date: Question 6. * Bart Childs : Question 34. * Bart Childs : Acknowledgements. * Bart Childs : Question 13. * Bart Childs : Question 24. * Bart Childs : Question 18. * Bugs: Question 32. * Bugs: General Questions/Bugs/Problems. * C: Question 1. * C++: Question 16. * C++: Question 1. * Cameron Smith : Question 30. * Cameron Smith : Question 29. * Change files: Question 18. * Command line options: Question 21. * Contents page: Question 24. * CWEB: Question 1. * CWEB: Question 16. * CWEB, @i option in: Question 29. * D.E. Knuth (DEK): Question 1. * David Thompson : Question 1. * David Thompson : Acknowledgements. * Debugger: Question 21. * Debugging: Question 22. * DEK (Donald E. Knuth): Question 1. * Design contributions: Question 1. * Distinguishing section names: Question 34. * Don Petcher : Question 33. * Don Petcher : Question 19. * Don Petcher : Acknowledgements. * Double sided pagination: Question 19. * FAQ for FWEB: Question 6. * FAQ Writer's Guide: Question 6. * FAQ, General: Question 6. * FILESERV: Question 6. * Floating bodies: Question 13. * Footnotes in LaTeX: Question 15. * Formatting: Question 1. * Fortran: Question 1. * Fortran--77: Question 35. * Fortran--90: Question 35. * Fortran90: Question 1. * Ftangle: Question 33. * ftangle, change allocation: Question 26. * ftangle, current allocation: Question 26. * ftn.sty: Question 15. * Function pointer: Question 20. * fweave: Question 28. * FWEB executables: Question 26. * FWEB for the PC: Question 10. * FWEB for the PC, precompiled files: Question 10. * FWEB sources: FWEB sources/Manual/Installation. * FWEB User's Manual: Top. * FWEB User's Manual, quoting: Question 5. * FWEB, future enhancements: Question 29. * FWEB, latest version: Question 9. * FWEB, painful work with: Question 11. * FWEB, v1.30-beta: Question 9. * fweb-faq: Question 6. * fweb-faq.dvi: Question 4. * fweb-faq.info: Question 4. * fweb-faq.ps: Question 4. * fweb-faq.texi: Question 4. * fwebmac.sty: Question 28. * fwebmac.sty: Question 19. * GCC: Question 12. * gcc-2.2.2: Question 11. * General Questions: General Questions/Bugs/Problems. * George D. Greenwade : Question 6. * Global scope: Question 33. * GNU C compiler (GCC): Question 1. * GNU Emacs editor: Question 18. * GNU Emacs editor: Question 4. * Hans-Hermann Bode : Question 10. * Hewlett-Packard: Question 12. * How can I contribute?: Question 6. * HP: Question 12. * Ian Kluft : Question 6. * Initialization file: Question 13. * Intel 80386: Question 11. * Introduction and Editorial: Introduction and Editorial. * JAK (John A. Krommes): Top. * JAK (John A. Krommes): Question 29. * JAK, quoted: Question 9. * JAK, quoted: Question 22. * JAK, quoted: Question 11. * JAK, quoted: Question 34. * JAK, quoted: Question 1. * JAK, quoted: Question 35. * JAK, quoted: Question 33. * JAK, quoted: Question 28. * Joachim Schrod : Acknowledgements. * Johannes Muller : Acknowledgements. * Johannes Muller : Question 22. * John A. Krommes (JAK): Top. * John Krommes : Question 11. * John Krommes : Question 1. * John Krommes : Question 32. * John Krommes : Acknowledgements. * Journal files: Question 18. * Language-specific: Question 20. * LaTeX: Question 13. * Lewis Perin : Question 15. * Lewis Perin : Question 14. * lex: Question 14. * limbo, style-file parameter: Question 24. * limbo.material: limbo.material. * limbo.material: Question 24. * limbo.sty: Question 24. * limbo.sty: limbo.sty. * linux-096c: Question 11. * Literate Programming, abbreviation for: Question 31. * LitProg Mailing List: Top. * LitProg-Request@shsu.edu: Question 2. * Local scope: Question 33. * Macro preprocessor: Question 1. * Macro preprocessor: Question 22. * mail-server@rtfm.mit.edu: Question 8. * Make: Question 12. * Makefile: Question 6. * Makefile: Question 17. * Makefiles, FWEB support: Question 17. * Marcus Speh : Top. * Mark Motl : Question 18. * Marmion, canto 6, verse xvii: Question 30. * Meta-comment: Question 22. * Microsoft C 6.00: Question 11. * MS-DOS: Question 21. * Multilingual WEB variant: Question 1. * Nathan Torkington : Question 6. * Native speaker: Question 30. * Nelson H. F. Beebe : Question 1. * niord.shsu.edu/FILESERV/LITPROG: Top. * Object-Oriented Literate Programming: Question 16. * Paul Lyon : Question 28. * PC: Question 1. * prep.ai.mit.edu:/pub/gnu: Question 4. * Programming, Literate (!): Question 1. * Question for the General FAQ: Question 1. * Question for the General FAQ: Question 31. * Question for the General FAQ: Question 29. * Question for the General FAQ: Question 30. * Ratfor: Question 1. * Ratfor: Question 35. * Ratfor processor: Question 26. * README.fweb-faq: Question 4. * Referencing: Question 23. * Reserved words: Question 20. * Richard Palais: Question 30. * Robert J. Chassell : Acknowledgements. * Sam Houston State University: Question 6. * Section names, referencing of: Question 23. * Silvio Levy : Question 1. * Silvio Levy : Question 16. * Sir Walter Scott : Question 30. * Steve Avery : Question 23. * SUBSCRIBE LITPROG: Question 2. * support porting FWEB: Question 11. * Sync lines: Question 21. * table: Question 13. * tabular: Question 13. * Tangle: Question 16. * Tero Laakkonen : Question 11. * TeX: Question 1. * Texinfo system: Question 4. * Thorbjoern Ravn Andersen : Acknowledgements. * Thorsten Ohl : Acknowledgements. * time.tex: Question 24. * time.tex: time.tex. * Title: Question 24. * Titlepage: Question 24. * To-do-list: Question 7. * Turbo C: Question 11. * UNIX: Question 1. * version 1.23b: Question 33. * VMS: Question 1. * Weave: Question 20. * WEB: Question 1. * WEB preprocessor: Question 22. * web-mode.el: Question 18. * William Shakespeare: Question 30. * yacc: Question 14. * Zdenek Wagner : Question 15. * [M-10.2]: Question 17. * [M-11.12]: Question 20. * [M-11.21]: Question 33. * [M-11.38]: Question 22. * [M-14.2]: Question 21. * [M-19.7.18]: Question 23. * [M-19.7.22]: Question 13. * [M-19.8]: Question 27. * [M-1]: Question 1. * [M-2.4]: Question 1. * [M-7.5]: Question 22. * \footnote, LaTeX: Question 15. * \identicalpageheadstrue: Question 19. * \modlabel: Question 23. * \output: Question 13. * \ref: Question 23. * \WEBsection: Question 23. * |, in LaTeX verbatim: Question 13. ////////////////////////////////////////////////////////// // marcus@x4u.desy.de // Marcus Speh // // [131.169.30.33] // II. Inst. f. Theor. Phys. // // Phone: (040) 8998-2260 // Luruper Chaussee 149 // // FAX: (040) 8998-2267 // 2000 Hamburg 50 / Germany // ////////////////////////////////////////////////////////// ================================================================================ Archive-Date: Mon, 11 Jan 1993 12:10:10 CST Message-ID: <9301111805.AA00069@im4u.cs.utexas.edu> From: leew@cs.utexas.edu (Lee Wittenberg) Reply-To: LitProg@SHSU.edu Date: Mon, 11 Jan 1993 12:05:23 -0600 To: LitProg@shsu.edu Subject: Re: bad CWEB formatting ? Klaus Elsbernd writes: > This mentioned problem is not only true if you use non-reserved words like > |line| as identifiers. I detected this problem in the following code > fragment too: > > @= > struct g_process { > int socket; > struct msgh *msgh; > char *buf; > char owner[10]; /* user-id des Benutzers */ > time_t connect_time; > time_t access_time; > time_t give_ivory_time; > #ifdef DAEMON > Board *p_board; /* ein zum \gproc-Proze\"s geh\"orendes board */ > struct g_process *next_g_process; > #else > int pid; /* process-id of a called process executing genera */ > #endif /* DAEMON */ > }; > > typedef struct g_process G_Process; > > The code formats to > = > struct g_process {int socket; > struct msg *msgh; > ... > #ifdef DAEMON > ... > #endif > }; typedef struct g_process G_Process; > > The solution is the same; I inserted > @f G_Process int > and CWEAVE did the right thing (insert a newline after the structure > definition). I hope I made it right and served not the symptom. Actually, my guess is that it was a different formatting problem in your case. We tend to forget that the WEB formatters are (deliberately) pretty simple. They deal well with all the usual suspects, but can't deal with more complicated stuff. It may be that the embedded #ifdefs, etc. are screwing up the parser. Another possibility: Is the typedef for Board before the section you describe? If not, the parser will not know that Board is "int_like" when it is parsing this section. If Board is in italics (rather than bold) in the woven version (before the fix), this is probably what happened. Or it could be something completely different. What the hell, the fix works (although it is always nice to know _why_ something works). -- Lee Wittenberg ================================================================================ Archive-Date: Mon, 11 Jan 1993 12:15:30 CST Message-ID: <9301111811.AA00626@im4u.cs.utexas.edu> From: leew@cs.utexas.edu (Lee Wittenberg) Reply-To: LitProg@SHSU.edu Date: Mon, 11 Jan 1993 12:11:55 -0600 To: LitProg@shsu.edu Subject: Re: Defining multiple modules (sections) in one Steve Avery writes (in response to an earlier message of mine): > leew> x = @ = 0; > > Okay, my two bits worth (again) - this is not a very good > example of literate programming (imho of course). I was under the > impression that this sort of code is best handled by the @d mechanism > which web provides. I would even be quite suprised if weave was able to > handle this sort of code, as I am sure it would have difficulty parsing > a section which did not contain complete statements. I agree completely with Steve that this is a bad example of literate programming and that an @d is much more appropriate. The point is that code like this exists (and there may be a more valid example out there), and the extra overhead involved in typing an extra @ is minimal compared to the extra overhead involved in making a more sophisticated parser that will almost certainly break existing code. -- Lee Wittenberg ================================================================================ Archive-Date: Mon, 11 Jan 1993 13:22:16 CST Date: Mon, 11 Jan 1993 13:20:26 CST From: "George D. Greenwade" Reply-To: LitProg@SHSU.edu To: LitProg@SHSU.edu CC: marcus@x4u.desy.de, r02kar@rec06.desy.de, krommes@lyman.pppl.gov, maarten@wuphys.wustl.edu, burow@vxdsya.desy.de, sokal@acf3.nyu.edu, edwards@ds2.scri.fsu.edu, rossen@ledaig.uwyo.edu, pasciak@jep.das.bnl.gov, KOVACS@fnald.fnal.gov Message-ID: <0096673B.9EA456A0.16056@SHSU.edu> Subject: RE: Announcement: fweb-faq [01-93] updated On Mon, 11 Jan 93 11:04:43 +0100, marcus@x4u.desy.de (Marcus Speh) posted about the update to his FAQ for FWEB. I have been a bad archivist on this and should have been quicker to point out my plans on this -- my sincerest apologies to Marcus about this, as well as any inconvenience this may cause you. Here is the major change at our site: > How to get the fweb-faq file(s): > -------------------------------- > Retrieve them via anonymous FTP from the following sites > > Name: niord.shsu.edu [official FWEB FAQ host] > Address: 192.92.115.8 > Directory: [FILESERV.FWEB] Please make this: > Directory: [FILESERV.FWEB-FAQ] where I have made a ZIP archive of the entire distribution, in addition to the individual files. Also: > To retrieve the (text) file via e-mail, include: > SENDME FAQ.FWEB > in the body of a mail message to FILESERV@SHSU.BITNET > (FILESERV@SHSU.edu). To retrieve the full family of files > (< 500 KByte), include SENDME FAQ.FWEB* instead. You can also use SENDME FWEB-FAQ for the entire distribution. I am appending the description file from FILESERV for your reference. I expect that this will be a stable placement (at least for now). Again, my apologies for any inconvenience this may cause. As always, thanks to Marcus for his leadership and effort in bringing this part of the Literate Programming FAQ to us. Regards, George %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% George D. Greenwade, Ph.D. Bitnet: BED_GDG@SHSU Department of Economics and Business Analysis THEnet: SHSU::BED_GDG College of Business Administration Voice: (409) 294-1266 P. O. Box 2118 FAX: (409) 294-3612 Sam Houston State University Internet: bed_gdg@SHSU.edu Huntsville, TX 77341 bed_gdg%SHSU.decnet@relay.the.net %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% FWEB-FAQ -------- The FWEB-FAQ package includes Marcus Speh's answers to frequently asked questions about the literate programming tool FWEB. This package includes a variety of formats for this file. The principal source file is written in Texinfo. The distribution now has a very simple Makefile for processing that source. Version 2.90 of the macro file "texinfo.tex" is included, which allows you to run plain TeX on the Texinfo source to obtain a DVI file (without index). A DVI file and a Postscript file (with index) are still included to satisfy everybody's needs. To retrieve the complete set of files, include: SENDME FWEB-FAQ in the body of a mail message to FILESERV@SHSU.BITNET (FILESERV@SHSU.edu). To retrieve a specific file, such as FWEB-FAQ.README, include: SENDME FWEB-FAQ.README in your mail message to FILESERV. For anonymous ftp retrieval, the complete distribution is available as a ZIP archive in the directory [FILESERV.FWEB-FAQ] on Niord.SHSU.edu (192.92.115.8). Files in this package: (1 Block = 512 bytes) File Blocks Save file as: ------------------------------------------------------------------------------- FWEB-FAQ. 104 fweb-faq FWEB-FAQ.ANNOUNCEMENT 9 Announcement FWEB-FAQ.DVI_UUE_1OF5 79 FWEB-FAQ.DVI_UUE FWEB-FAQ.DVI_UUE_2OF5 79 UUDECODEs to fweb-faq.dvi FWEB-FAQ.DVI_UUE_3OF5 79 FWEB-FAQ.DVI_UUE_4OF5 79 FWEB-FAQ.DVI_UUE_5OF5 20 FWEB-FAQ.MAKEFILE 14 Makefile FWEB-FAQ.PS_1OF7 79 fweb-faq.ps FWEB-FAQ.PS_2OF7 79 FWEB-FAQ.PS_3OF7 79 FWEB-FAQ.PS_4OF7 79 FWEB-FAQ.PS_5OF7 79 FWEB-FAQ.PS_6OF7 79 FWEB-FAQ.PS_7OF7 18 FWEB-FAQ.README 12 fweb-faq.README FWEB-FAQ.TEXI 116 fweb-faq.texi FWEB-FAQ.TEXINFO_TEX_1OF4 79 texinfo.tex FWEB-FAQ.TEXINFO_TEX_2OF4 79 FWEB-FAQ.TEXINFO_TEX_3OF4 79 FWEB-FAQ.TEXINFO_TEX_4OF4 10 Approximate total blocks in full FWEB-FAQ package = 1330 NOTE: The file FWEB-FAQ. is identical to the FAQ.FWEB file found in the FAQ package on FILESERV and the FAQ.FWEB file found in [FILESERV.FAQ] on Niord.SHSU.edu. ================================================================================ Archive-Date: Wed, 13 Jan 1993 23:43:23 CST Date: 14 Jan 93 00:04:13 EST From: Anthony Panos <72537.332@CompuServe.COM> Reply-To: LitProg@SHSU.edu To: Lit Programming Subject: unsubscribe Message-ID: <930114050413_72537.332_DHJ52-2@CompuServe.COM> unsubscribe litprog ================================================================================ Archive-Date: Fri, 15 Jan 1993 08:27:38 CST Date: Fri, 15 Jan 93 09:23:34 -0500 From: ae1181t@stnfor.ae.ge.com (Osman F Buyukisik) Reply-To: LitProg@SHSU.edu Message-ID: <9301151423.AA21628@stnfor.ae.ge.com> To: litprog@shsu.edu Subject: fweb manual I tried to TeX the manual but it failed due to missing "equiv.tex" file. Does anyone have this file? Or is there postscript file already made? thanks 8-)( ================================================================================ Archive-Date: Fri, 15 Jan 1993 09:28:56 CST Date: Fri, 15 Jan 93 16:24:29 +0100 From: marcus@x4u.desy.de (Marcus Speh) Reply-To: LitProg@SHSU.edu Message-ID: <9301151524.AA07948@x4u.desy.de> To: LitProg@SHSU.edu Subject: fweb manual References: <9301151423.AA21628@stnfor.ae.ge.com> CC: "John A. Krommes" |> I tried to TeX the manual but it failed due to missing "equiv.tex" file. |> Does anyone have this file? Or is there postscript file already made? |> thanks /anonymous@lyman.pppl.gov:/pub/fweb/v1.30/manual: -rw-r--r-- 1 4145 589 1554 Jan 14 18:32 equiv.tex The User's Manual for the (stable) version 1.23a did not require equiv.tex, it seems. Anyway, according to the READ_ME file you should not expect that all the subdir's of v1.30 are complete since v1.30 is BETA. v1.23 contains DVI output for all the parts of the manual. To begin with FWEB that should be sufficient. --Marcus Speh -- ================================================================================ Archive-Date: Wed, 20 Jan 1993 03:39:28 CST Date: 20 Jan 1993 10:35 +0000 (GMT) From: "Eric W. van Ammers, LUW, tel: (+31)8370-83356" Reply-To: LitProg@SHSU.edu Subject: Literate Programming?: Why not routines instead To: LITPROG@shsu.edu Message-ID: <01GTQLQSMXHS8WW85W@RCL.WAU.NL> LP versus procedures I have been practicing literate programming for a long time and I feel very happy with it. But very often when I try to explain what literate programming is about, I get confused if people ask me what the advantages of LP are compared to working with small independent well documented routines. My experience learns me that there is a big difference indeed, but I untill now I am not able to make this expicite. Note that Knuth in his 1984 paper in The Computer Journal also avoided this point My question to you, LITPROG netters, is to give me your opinion and suggestions with respect to the problem above. Eric W. van Ammers (ammers@rcl.wau.nl) ================================================================================ Archive-Date: Wed, 20 Jan 1993 15:34:01 CST Message-ID: <9301202129.AA13423@im4u.cs.utexas.edu> From: leew@cs.utexas.edu (Lee Wittenberg) Reply-To: LitProg@SHSU.edu Date: Wed, 20 Jan 1993 15:29:19 -0600 To: LitProg@shsu.edu Subject: Re: Literate Programming?: Why not routines instead Eric W. van Ammers writes: > I have been practicing literate programming for a long time and I feel very > happy with it. But very often when I try to explain what literate programming > is about, I get confused if people ask me what the advantages of LP are > compared to working with small independent well documented routines. > > My experience learns me that there is a big difference indeed, but I untill > now I am not able to make this expicite. Note that Knuth in his 1984 paper > in The Computer Journal also avoided this point The FWEB User's manual has a nice discussion of this issue (section 4.11 in the version 1.23 manual). If you can't get hold of it, I'm sure John Krommes would give permission to quote it here. Knuth does address the issue somewhat (I recall) in one of the papers in his new Literate Programming book. I'm not sure which one it was. Does anyone out there know the reference? -- Lee Wittenberg ================================================================================ Archive-Date: Wed, 20 Jan 1993 15:50:19 CST Date: Wed, 20 Jan 93 22:45:48 +0100 From: dak@POOL.informatik.rwth-aachen.de Reply-To: LitProg@SHSU.edu Message-ID: <9301202145.AA03240@messua> To: LitProg@SHSU.edu Subject: Re: Literate Programming?: Why not routines instead >From: "Eric W. van Ammers, LUW, tel: (+31)8370-83356" >LP versus procedures > >I have been practicing literate programming for a long time and I feel very >happy with it. But very often when I try to explain what literate programming >is about, I get confused if people ask me what the advantages of LP are >compared to working with small independent well documented routines. > >My experience learns me that there is a big difference indeed, but I untill >now I am not able to make this expicite. Note that Knuth in his 1984 paper >in The Computer Journal also avoided this point Often you cannot really avoid lengthy routines without having to formulate formal parameters, calling conventions etc. In the WEB approach (not in all LPs, of course), documentation can include readable mathematical formulas, which I consider a boon. The problem is, that small, well documented procedures do the job as well. However, you have to formulate calling parameters and other conventions. Not only that they complicate comprehension slightly, you will simply not find any programmer intent on serious work doing that. The advantage of LitProg over small, well documented procedures is simply psychological: splitting into sections a more complicated thing is easy and done on the fly, splitting a procedure into distinct procedures is a pain in the, needs additional consideration, reediting and restructuring. So it simply isn't done. Chances are, when you get both a LitProg program developped in haste and with only a small amount of documentation beside the code, and a procedural approach, that an outsider will with the LitProg understand much more after a reasonable investment of time, than with the normal program. That is because the structure of the program is more obvious, although not necessarily by being split into disjoint procedures. ================================================================================ Archive-Date: Wed, 20 Jan 1993 18:08:25 CST Date: Wed, 20 Jan 93 22:11:41 GMT From: mfy@sli.com (Mike Yoder) Reply-To: LitProg@SHSU.edu Message-ID: <9301202211.AA02602@ravel.sli.com> To: LitProg@SHSU.edu Subject: Literate Programming?: Why not routines instead Good day all. You, Eric W., asked: >I have been practicing literate programming for a long time and I feel very >happy with it. But very often when I try to explain what literate programming >is about, I get confused if people ask me what the advantages of LP are >compared to working with small independent well documented routines. The reason you are "confused" is that the question is somewhat like being asked, "Are you still beating your wife?" The problem is the presupposition that is behind the question. There is no such thing as "small independent well documented routines" for any program of a significant size. Many people think they write them, but if you try the only empirical test that matters--namely, seeing what happens when someone else tries to use these routines when the author is gone--you will almost certainly find it works badly. Now, if you confront the author with this fact, the last thing that will happen is that he or she will say "Oh, drat. I guess they weren't well enough documented after all." What they will instead say is "that person was just too dumb to understand my code." Please don't take this example too literally; I'm trying to get my point across in one try, and I need vivid imagery. Unfortunately, I suspect this line of argument will be unconvincing, and you will have to find another one. There will probably be responses saying they have seen examples where my claim isn't true, but I am going to disqualify a whole slew of them right off the top. I, too, have had cases where the approach seemed to work *when the original author was available for consultation*. But this is not documentation; it is documentation plus folklore, and the folklore is usually critical. As far as I'm concerned, documentation is not adequate unless it would suffice if the original author fell under a bus and became permanently unavailable to the new programmer. *This* is rare, and Literate Programming does not guarantee it, but it makes it much more likely. I also realize that it is possible to get by without really understanding the code; this approach "works" in roughly the same sense that Communism "worked" in the U.S.S.R. up to the point it collapsed. Good luck with your discussions. Michael Yoder ================================================================================ Archive-Date: Wed, 20 Jan 1993 22:40:18 CST Date: Wed, 20 Jan 93 23:35:29 EST From: pcolsen@super.org (Peter C Olsen) Reply-To: LitProg@SHSU.edu Message-ID: <9301210435.AA02246@super.super.org> To: LitProg@SHSU.edu Subject: WEB for C++? Perhaps this is a FAQ, but has anyone seen a WEB for C++? I have a copy of cpp2latex, but I would like to try a full-fledged WEB. Peter Peter Olsen, n2ell, pcolsen@super.super.org ...!uunet!super!pcolsen P.O. Box 410, Simpsonville, MD 21150; 410-997-8584 "Engineering is the art of applying a professional knowledge of mathematics and the physical sciences to improve the quality of life" ================================================================================ Archive-Date: Thu, 21 Jan 1993 03:48:31 CST Date: Thu, 21 Jan 93 09:04:10 GMT From: "Glyn Normington" Reply-To: LitProg@SHSU.edu To: litprog@shsu.edu Subject: Re: Literate Programming?: Why not routines instead >From: "Eric W. van Ammers, LUW, tel: (+31)8370-83356" >LP versus procedures > >I have been practicing literate programming for a long time and I feel very >happy with it. But very often when I try to explain what literate programming >is about, I get confused if people ask me what the advantages of LP are >compared to working with small independent well documented routines. > >My experience learns me that there is a big difference indeed, but I untill >now I am not able to make this expicite. Note that Knuth in his 1984 paper >in The Computer Journal also avoided this point Literate programming lets you structure your program into smaller chunks without the run-time overhead of a subroutine or the effort of writing a macro. It also has the advantage that a literate program is more than a collection of program fragments as there may be high-level design documentation included which would not fit nicely into a convention program. The literate programming tools I use allow multiple programs and other files to be generated from a single literate program (which may itself be split into multiple files using an imbed mechanism). This enables better grouping of programs and data which form abstract datatypes, which our base programming language does not support. Glyn Normington CICS Products, IBM UK Laboratories Ltd, Winchester, Hants, England. ================================================================================ Archive-Date: Thu, 21 Jan 1993 04:11:52 CST Date: Thu, 21 Jan 93 10:59:27 MDT From: Zdenek Wagner Reply-To: LitProg@SHSU.edu Subject: LP / procedures To: Literate Progaramming list At the beginning I would extend the postulate about non-existence of small well documented procedures. From my own experience I know that my own small well documented procedures do not work when transferred into another program half year later. However, I can see how procedures can live together with LP. I am now webifying my old C++ programs. During past non-literate times I develo ped a buch of general procedures and pure virtual classes which I put into private libraries in order to save compilation and linkage time. My intention for the future is to write such procedures and classes in web, compile them separately and place them into libraries. In this way I would take advantages of both LP and independent procedures and moreover I will save disk space since good web files tend to be long. Regards , ,~~~/ /` / /| /~~~ / / |_/ /__/ ' | / / /~~/ /~~/ /~~/ /~~/ /\ | /| / /~~/ /~~/ /~~/ /~~/ /~~~ / , / / /~~~ / / /~~~ / \ |/ |/ / /_/ / / / /~~~ / ~~~~ ~~~ ~~~ ' ' ~~~ ' ` ~~~ ~~/ ' ' ~~~ Zdenek Wagner______/ ================================================================================ Archive-Date: Thu, 21 Jan 1993 04:40:30 CST From: Joachim Schrod Reply-To: LitProg@SHSU.edu Message-ID: <9301211035.AA10845@spice.iti.informatik.th-darmstadt.de> Subject: Re: WEB for C++? To: LitProg@SHSU.edu Date: Thu, 21 Jan 1993 11:35:14 +0100 (MEZ) You wrote: > > Perhaps this is a FAQ, but has anyone seen a WEB for C++? Both FWEB and the new CWEB (not yet out, but RSN) are said to support C++. In fact, my experience shows that they don't -- they support a reasonable subset. Eg, templates and exceptions are something which is still missing. Of course, this comments apply only to the WEAVE parts, not to the TANGLE parts. -- Joachim =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= Joachim Schrod Email: schrod@iti.informatik.th-darmstadt.de Computer Science Department Technical University of Darmstadt, Germany @d infinity=255 {$\infty$ (approximately)} [DEK, in weave.web] ================================================================================ Archive-Date: Thu, 21 Jan 1993 04:43:59 CST Date: Thu, 21 Jan 93 11:39:57 +0100 From: marcus@x4u.desy.de (Marcus Speh) Reply-To: LitProg@SHSU.edu Message-ID: <9301211039.AA14355@x4u.desy.de> To: LitProg@SHSU.edu Subject: WEB for C++? References: <9301210435.AA02246@super.super.org> >>>>> On Wed, 20 Jan 93 23:35:29 EST, pcolsen@super.org (Peter C Olsen) said: > Perhaps this is a FAQ, but has anyone seen a WEB for C++? I have a > copy of cpp2latex, but I would like to try a full-fledged WEB. This is a FAQ. Try Question [16] in the fweb-faq: You may obtain the latest version of this FAQ via anonymous FTP from - `niord.shsu.edu' [192.92.115.8] in directory `[FILESERV.FWEB]', - `lyman.pppl.gov' [192.55.106.129] in directory */pub/fweb/faq*, - `ftp.imada.ou.dk' [129.142.128.14] in directory `/pub/faq', and `ftp.uni-stuttgart.de' [130.83.55.75] in directory `pub/soft/tex/web/fweb'. either .texi, .dvi, .ps, .info or plain text. --Marcus Speh -- ================================================================================ Archive-Date: Thu, 21 Jan 1993 06:56:29 CST Date: Thu, 21 Jan 93 13:52:37 +0100 From: marcus@x4u.desy.de (Marcus Speh) Reply-To: LitProg@SHSU.edu Message-ID: <9301211252.AA18686@x4u.desy.de> To: LitProg@SHSU.edu Subject: Philonous and Malevolent References: <01GTQLQSMXHS8WW85W@RCL.WAU.NL> CC: "Eric W. van Ammers" Cameron Smith , Eve Kovacs , "Francesca M. Borzumati" In my tirade, Philonous (Ph) is a friend and user of the WEB environment. He is arguing with Malevolent (Ma) who's finally going to join the LitProg family. Eventually he'll pick up a better name for himself. [Malevolent still has a hard time to believe though that CWEB++ is the "only True Web", and he will start and stay with FWEB] IMO, this socratic dialogue could actually have happened like this. They start as suggested by Eric van Ammers: Ma: "What are the advantages of LitProg compared to working with small independent well documented routines?" Ph: "One can still work with small, independent routines. They're just better documented now." Ma: "I can do well without TeX for documentation." Malevolent obviously does not believe in DEK. You wonder who's paying him. Philonous does not really know how to answer to that. He probably does not like troff. Or maybe Malevolent has got an eye problem? Ma: "In fact, I hate to spend to much time thinking about how to explain things to others when I haven't even finished the program." Ph: "Before I saw WEB, I wasted lots of time finding the right balance between doc and code. With WEB, it becomes easier to write doc along with the code. And update it." I have only experiences with FWEB, and I haven't been using it for more than one year. Before that, quite a lot of my time went into trying to improve on the delicate balance between documentation and code. None of my private efforts were really satisfying, though. Maybe also because (like many people outside of CS) I never really learnt how to program. Malevolent knows much more about programming, but he's got other things to do as well: Ma: "But isn't this a hell of a lot of extra effort?" Ph: "When I saw FWEB, I wasn't even put off because of the extra effort in learning something new. Though I must confess that I asked people in my field of research how long they had needed to get accustomed to the new tool." Since then, I freely give away the magic number of "10 days"--- if you know [La]TeX and the language(s) you want to code in. Ma: "Ok,Ok,Ok. Now, if you compare how much time it costs you and how much you gain?" (Malevolent is a tough calculator,it seems. He obviously got the message of the zeitgeist.) Ph: "I cannot speak for you. LitProg also is a matter of taste. It is a useful tool for me. It definitely increased my level of reflection upon what I was doing. It saves me time because the programs mostly *do* run in the first place - it costs me time because I now like to treat many otherwise neglectable pieces of code like little diamonds - and cannot be sure that this will pay besides aesthetics." Ma: "Of course I have heard about WEB. But I do not know anyone who is practicing it, really." (Later, Philonous will tell him about the LitProg list.) Ph: "True. The `evangelization' part sometimes is the most painful. There's no company working for WEB's success. No commercials placed. Thus, it definitely costs time because I am trying to convince my colleagues that they should try *WEB, too. But I am a born missionary anyway and so this meets my needs as well." (He did not really have to emphasize the last point...) The time for our key-hole listening is running out. It suffices to say that the two are having a lot more to discuss. At the end, Malevolent (overloaded with manuals, introductory texts, faqs, eager to try WEB) wants some advice how to evangelize others: Ma: "Assuming you meet someone who's more benevolent than I am-- how're you proceeding?" Ph: "Upon meeting someone who likewise seems to suffer likewise, and who signalizes a genuine interest in learning something new, I first show him a HUGE woven output [yes, I am carrying such a volume around mainly for that purpose]. Before putting the word "WEB" into my mouth I want to hear a SIGH when he is confronted with something which looks unlike anything he has seen yet. Even better if I have presented some more or less complicated program in a talk before: then people are lost and WEAVE's output comes handy to explain---it has got tables, it has got plots, maybe, an index, a table of contents--- Fine. Then the victim usually asks: `why did you put up all the extra work?'" Ma: "That almost sounds like me, before I had seen the light!" Ph: "Yes, that is the moment of truth indeed." (Timothy Murphy would much better know how to put it, I'm sure ;-) Ph: "I start explaining some things for real [forcing the victim to recur to the BEAUTIFUL output in regular intervals determined by the amount of healthy scepticism he's mobilizing to shield himself]. Eventually I show a not-too-complicated .web file. And I give him the speech which I gave you already, my friend. Of course: If I have a FWEB-FAQ (*) output at hand, I'll pass it to him, too." You have to judge whether this may happen with your colleagues in the same way. Mine are definitely special in that many of them are used that everything comes to them pre-digested. If that is not the case, they'd rather cut on their needs: for fine documentation, for well-structured code etc. Probably this will not hold for the majority of LitProg's readers. --Marcus Speh -- ---------------------------------------------------------------------- (*) You may obtain the latest version of this FAQ via anonymous FTP from - `niord.shsu.edu' [192.92.115.8] in directory `[FILESERV.FWEB]', - `ftp.imada.ou.dk' [129.142.128.14] in directory `/pub/faq/fweb' - `ftp.uni-stuttgart.de' [130.83.55.75] in directory `pub/soft/tex/web/fweb/FAQ'. - `lyman.pppl.gov' [192.55.106.129] in directory `/pub/fweb/faq' (Texinfo/text only) either as .texi, .dvi, .ps, .info or plain text file. ////////////////////////////////////////////////////////// // marcus@x4u.desy.de // Marcus Speh // // [131.169.30.33] // II. Inst. f. Theor. Phys. // // Phone: (040) 8998-2260 // Luruper Chaussee 149 // // FAX: (040) 8998-2267 // 2000 Hamburg 50 / Germany // ////////////////////////////////////////////////////////// ================================================================================ Archive-Date: Thu, 21 Jan 1993 07:38:03 CST Date: Thu, 21 Jan 93 08:35:12 -0500 From: koopman@sgi84.ctc.com (Michael G. Koopman) Message-ID: <9301211335.AA26023@sgi84.ctc.com> To: LitProg@SHSU.edu CC: LITPROG@shsu.edu Subject: Literate Programming?: Why not routines instead Reply-To: LitProg@SHSU.edu In a message of 20 Jan 1993, Eric W. van Ammers writes: > I have been practicing literate programming for a long time and I feel very > happy with it. But very often when I try to explain what literate programming > is about, I get confused if people ask me what the advantages of LP are > compared to working with small independent well documented routines. > ... > My question to you, LITPROG netters, is to give me your opinion and suggestions > with respect to the problem above. I am highly underqualified to respond to this question, therefore, I feel it is my responsibility to broadcast my naiveity by the widest distribution channel to which I have access, namely, the net. So .... I admit only limited "book knowledge" of Literate Programming, including information from texts, journals, magazines and coffee houses. Perhaps others, like Eric W. van Ammers, who have first-hand, experiential knowledge of LP can judge the validity of the following benefits which I have presumed. First, and foremost, LP provides associativity or "links" between the comments and the coding. This seems obvious in the name "Web" and a plausible influence on the name choice. This associativity knowledge is used, primitively, by LP compilers as I know them. That is, the links are used strictly as handles to the associated information. However, this associativity allows for "meta-compiler" activities not easily supported by well-documented code which is not LP. The meta-compiler activities could include such actions as automated commonality detection leading to abstraction via machine reasoning. With limited natural language processing of the comments, in conjunction with the associations identified by the code linkage, elements of the code such as contexts and intention may be derived. A meta-compiler which interprets software with such abstract knowledge makes possible software engineering methods I can not even imagine at this time. Advanced compilers could be developed which perform abstract knowledge interpretation of well-documented modules, but LP should make such activities easier. Qualified comments about intentional programming are requested, I merely prattle. It also seems LP can help to bridge the gap between the languages. Being unlikely that one code paradigm can offer the "right choice" for all programs, LP should help in designing and maintaining large programs. Such are often composed of large subprogram modules in different languages. This requires an LP system which accepts more than one compiled language code component, e.g., C, C++, Pascal and Smalltalk. Mike Koopman e-mail: koopman@server1.ctc.com Concurrent Technologies Corporation phone: +1-814-269-2637 1450 Scalp Avenue telefax: +1-814-269-2666 Johnstown, PA 15904 USA ICBM: 40-15'N-78-50'W Std. Disclaimer: Similarity to anyone living or dead is coincidental. ================================================================================ Archive-Date: Thu, 21 Jan 1993 08:36:23 CST From: Timothy Murphy Reply-To: LitProg@SHSU.edu Subject: Re: WEB for C++? To: LitProg@shsu.edu Date: Thu, 21 Jan 93 14:31:42 GMT Sender: tim@maths.tcd.ie Message-ID: <9301211431.aa01619@salmon.maths.tcd.ie> > Perhaps this is a FAQ, but has anyone seen a WEB for C++? I have a > copy of cpp2latex, but I would like to try a full-fledged WEB. The latest version of CWEB is called cweb++2.9 , and seems to cover C++. Unfortunately it doesn't appear to have been released officially, although it has been about for some time. Could we have it now, please, Silvio and Don (Levy & Knuth)? Please. Timothy Murphy e-mail: tim@maths.tcd.ie tel: +353-1-2842366 (home/office) +353-1-7021507 (university) fax: +353-1-2842295 s-mail: School of Mathematics, Trinity College, Dublin 2, Ireland ================================================================================ Archive-Date: Thu, 21 Jan 1993 09:41:27 CST Message-ID: <9301211537.AA12046@tampa.berkeley.edu> To: LitProg@shsu.edu Subject: Re: WEB for C++? CC: levy@geom.umn.edu Date: Thu, 21 Jan 93 07:37:49 -0800 From: Silvio Levy Reply-To: LitProg@SHSU.edu > From: Joachim Schrod > In fact, my experience shows that [FWEB and the new CWEB] > don't [support C++] -- they support a > reasonable subset. Eg, templates and exceptions are something which is > still missing. There is now support for templates in CWEB. It is still being tested. I don't know what "exceptions" are. Silvio ================================================================================ Archive-Date: Thu, 21 Jan 1993 12:44:52 CST Message-ID: <9301211840.AA15224@fernwood.mpk.ca.us> From: Roger_Alexander@rock.intersolv.com Reply-To: LitProg@SHSU.edu Date: 21 Jan 93 12:04 To: LitProg@SHSU.edu Subject: CWEB++ How can one obtain the latest copy of CWEB++ ? Thanks, Roger Alexander roger_alexander@intersolv.com ================================================================================ Archive-Date: Thu, 21 Jan 1993 16:24:36 CST Date: Thu, 21 Jan 93 23:20:05 +0100 From: dak@POOL.informatik.rwth-aachen.de Reply-To: LitProg@SHSU.edu Message-ID: <9301212220.AA21837@tabaqui> To: LitProg@SHSU.edu Subject: Re: Philonous and Malevolent Oops, wrong subject. Well one obvious argument for webs over small, well documented routines is especially nice: Ask the offender, who hopefully believes in small routines, how often it has happened that she wished the measure of indents was smaller than 8 because her lines wrapped when correctly indenting. Oh, she indents only 4? How is one supposed to immediately see what belongs together? Oh, use a ruler? Well, how am I supposed to know what this third brace from the bottom in this small, only 2-page procedure, belongs to, so that I know what the if before that is about? Hmmmm, interesting. Does she know the >> and << commands from vi? Oh, she uses them all the time? Appealing. Obviously, anybody who gets along that great does not need LitProg. ================================================================================ Archive-Date: Fri, 22 Jan 1993 02:10:49 CST Message-ID: <9301220802.AA21875@mistral.imag.fr> From: Yves Arrouye Reply-To: LitProg@SHSU.edu Date: Fri, 22 Jan 1993 09:02:23 +0100 To: Litprog@SHSU.edu Subject: WEB support for Objective C? Does anybody know if there is a web supporting Objective C, or if somebody is currently working on adding such a support to fweb? -- Elle e'tait comme je vous la raconte sans que vous Yves Arrouye puissiez voir son visage ni entendre ses paroles, arrouye@mistral.imag.fr pas plus que je ne l'ai vu ni ne les ai entendues, arrouye@imag.imag.fr moi qui pourtant les ai si bien connus. (33) 76 57 48 61 ================================================================================ Archive-Date: Fri, 22 Jan 1993 02:44:20 CST Date: 22 Jan 1993 09:38 +0000 (GMT) From: "Eric W. van Ammers, LUW, tel: (+31)8370-83356" Reply-To: LitProg@SHSU.edu Subject: Information please To: LITPROG@shsu.edu Message-ID: <01GTTCCJP15C8WWEB1@RCL.WAU.NL> LP versus procedures With regard to my problem of LP versus procedures, Lee Wittenberg writes: >The FWEB User's manual has a nice discussion of this issue (section 4.11 in >the version 1.23 manual). If you can't get hold of it, I'm sure John Krommes >would give permission to quote it here. >Knuth does address the issue somewhat (I recall) in one of the papers in >his new Literate Programming book. I'm not sure which one it was. Does >anyone out there know the reference? I have the following questions: - Is the FWEB User's manual FTP-able and if so, from which node (I could not find it on NIORD) or - can someone supply a fax-copy of the above referred section to Eric W. van Ammers Computer Science Department Wageningen Agricultural University fax: +31 (0)8370 84731 - Who can give me a more precise reference to Knuth's discussion on this point. Eric W. van Ammers (ammers@rcl.wau.nl) ================================================================================ Archive-Date: Fri, 22 Jan 1993 09:49:38 CST Date: Fri, 22 Jan 1993 09:48:55 CST From: "George D. Greenwade" Reply-To: LitProg@SHSU.edu To: LitProg@SHSU.edu CC: ammers@rcl.wau.nl Message-ID: <00966FC2.E5816740.20007@SHSU.edu> Subject: RE: Information please On 22 Jan 1993 09:38 +0000 (GMT), "Eric W. van Ammers, LUW, tel: (+31)8370-83356" posted: > With regard to my problem of LP versus procedures, Lee Wittenberg writes: > > >The FWEB User's manual has a nice discussion of this issue (section 4.11 in > >the version 1.23 manual). If you can't get hold of it, I'm sure John Krommes > >would give permission to quote it here. > > >Knuth does address the issue somewhat (I recall) in one of the papers in > >his new Literate Programming book. I'm not sure which one it was. Does > >anyone out there know the reference? > > I have the following questions: > - Is the FWEB User's manual FTP-able and if so, from which node (I could > not find it on NIORD) or > - can someone supply a fax-copy of the above referred section to > Eric W. van Ammers > Computer Science Department > Wageningen Agricultural University > fax: +31 (0)8370 84731 > - Who can give me a more precise reference to Knuth's discussion on this > point. The manual is contained within the distributions of FWEB. However, I just unpacked the manual directory and created the manual, which now appears on Niord.SHSU.edu (192.92.115.8) in [FILESERV.FWEB]FWEBMAN-V1_23.* in PostScript as well as the raw DVI file. Since we don't have make on our VMS machine, I simply tex'xed the fwebman.tex file (which appears to have done everything as advertised in the Makefile). Note that this is a 168 page document (I didn't look for the specific section to determine its size). Anyway, it's there now if you want to retrieve it. Regards, George %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% George D. Greenwade, Ph.D. Bitnet: BED_GDG@SHSU Department of Economics and Business Analysis THEnet: SHSU::BED_GDG College of Business Administration Voice: (409) 294-1266 P. O. Box 2118 FAX: (409) 294-3612 Sam Houston State University Internet: bed_gdg@SHSU.edu Huntsville, TX 77341 bed_gdg%SHSU.decnet@relay.the.net %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% ================================================================================ Archive-Date: Fri, 22 Jan 1993 17:37:14 CST Date: Fri, 22 Jan 93 23:27:19 GMT Message-ID: <9613@apusapus.demon.co.uk> From: tfj@apusapus.demon.co.uk (Trevor Jenkins) Reply-To: LitProg@SHSU.edu To: LitProg@shsu.edu Subject: A programmer's first use of Literate Programming I'm five days into my first real use of Literate Programming. I thought that it might be of interest to some to read my observations. Firstly, some background; I'm a programmer of approx 15 years experience. I would claim that I write good code but with the usual slips in it. Like the other day when I type + rather than - in an atoi type routine! My programming style can best be described as "middles-out" neither "top-down" nor "bottom-up" but expoliting both strategies simultaneously. The second bit of background, I attended the London meeting where DEK gave his first presentation of Literate Programming. I knew this was IT. This was a methodology that I could use without changing my style or habits but which would give them some rigour and provide me with a "mechanical" aid to organise the pieces into the final program. None of my colleagues who attend that meeting saw the necessity for what we know of as WEB. The third bit of background. I'd ban programmers from using terminals for program development! They should have to rely upon decks of cards and have to run up seven flights of stairs to submit their deck for its only run of the day. Well that's what I had to do when I started 15 years ago. However, I firmly believe that the quality of my code dropped dramatically the day I had access to a terminal. When I used a batch system I did all those things that we know we should do: desk checking, dummy runs, peer review. Now to today. The project I'm involved in is to convert data from one proprietary format (USMARC) to another! The target format is very simple. Unpicking the rats nest of MARC format is not simple. Therefore I decided to use WEB (CWEB in reality) to write this convertor. I've so far not tried to compile the code for real and I don't have TeX readily available! I'm writting the application in the office but TeX is only installed on a PC at home. Weave and Tangle are installed at both ``sites''. I run the WEB source through cweave fairly frequently at check that there are no sections missing (or more likely mis-speelt); a couple of times I've run the generated C code through a compiler which has picked up a few mis-typed identifier names. Whilst I've been working on this program I've been amazed at the ease with the code can be written. I'd probably have written the same amount by now. I'd have tried compiling it endless times and gotten more and MORE and MOREEE frustrated. Using WEB has allowed me to concentrate upon the microscopic concerns without having to be so concerned with the macroscopic structure. Yet I was surprised by the ease with which I could flip between the sections and still hold the whole structure in my head at the same time. Even to the point of changing a major data structure mid-way, the effect that this would have had upon me in the past would only have been overshadowed by the effect upon the code itself. As it is the changes are very localised into one or two sections and the knock on effect was non-existant. I have delayed running the woven output through TeX until tonight. The only problem with this was that I'm running CWEB 2.8 on the office VAX and 2.7 on my PC. When I saw the output I started to read and there it was (or rather there they were) errors. Sure I'd have found them eventually when I got a segmentation fault or an access violation but it was just like the early days, spot the errors when their still on the desk. Think of the journey home as the climb up those seven flights of stairs. ;-) My boss wont apprecaite the use of CWEB. My current boss wasn't one of those who hear DEK speak indeed they dont even know how to program, they'll only see that the task is complete. It'll be seen as an unecessary complication! But I'll know that the code is solid and that it'll work properly even in the presence of incorrect data. The customer will be unaware as well. A few things could make Literate Programming even better. A Windows based WEB developement editor that caught mis-typed fragment names, that detected errors in the C code (such as mis-spelt identifier names). I glad that I went to that lecture all those years ago, I've been infatuated with WEB ever since but today I fell in love. :-) Regards, Trevor. --------------------------------------------------------------------------- Trevor Jenkins Re: "deemed!" 134 Frankland Rd, Croxley Green, Rickmansworth, WD3 3AU, England email: tfj@apusapus.demon.co.uk radio: G6AJG phone: +44 (0)923 776436 ================================================================================ Archive-Date: Sun, 24 Jan 1993 15:06:49 CST Date: Sun, 24 Jan 1993 15:06:39 CST From: "George D. Greenwade" Reply-To: LitProg@SHSU.edu To: LitProg@SHSU.edu Message-ID: <00967181.9C6234C0.25630@SHSU.edu> Subject: RE: A programmer's first use of Literate Programming On Fri, 22 Jan 93 23:27:19 GMT, Trevor Jenkins posted a very good overview (at least in this totally naive watcher's opinion) of first efforts at CWEB. Quite honestly, I will probably never appreciate what it is that is being accomplished by Literate Programming nor what is facilitated on LitProg because I am not (nor do I really desire to be) a programmer. I can read just enough code to be dangerous; indeed that's why we have the specialists in our Computer Services division as well as those of you on this list. As a long-time (18 years now; gosh, I'm a dinosaur) non-programming user, I can appreciate his comments on limited runs, flights of stairs, cards, etc. (everyone should have to do that at least briefly to really appreciate where computing has moved in a relatively short time period). One point in the post which I would like to comment on, though: > My boss wont apprecaite the use of CWEB. My current boss wasn't one of > those who hear DEK speak indeed they dont even know how to program, they'll > only see that the task is complete. It'll be seen as an unecessary > complication! But I'll know that the code is solid and that it'll work > properly even in the presence of incorrect data. The customer will be > unaware as well. This is exactly where Literate Programming needs to be developed! If my understanding of what the WEB-type family of tools is correct, Literate Programming is very likely the most economic way of writing available to date. While the initial project may or not have been expedited, it is my guess that revisions are significantly easier since the original code fragments are intentionally and by design better documented. The customer, while initially unaware of how what got where, will be aware that at least it did. The customer will very likely need some form of support, if not another complete overhaul of proprietary-to-proprietary formats sometime in the future since that appears to be the nature of competition in proprietary software. When those times come, again assuming I am cognizant of what Literate Programming allows, the process should be somewhat more streamlineable. At that point, your boss will be appreciative (or at least should be). Recognizing the managerial aspects of Literate Programming may very soon be a topic I pursue in the study of economics (occasionally I have to satisfy my poobahs that what I do on the net has something to do with the field of economics, so why not?). Are my views outlined above misguided? If not, I may have stumbled upon a gold mine of research topics and will willingly serve as a naive disciple attempting to win converts in the managerial side on the advantages of Literate Programming. Regards, George %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% George D. Greenwade, Ph.D. Bitnet: BED_GDG@SHSU Department of Economics and Business Analysis THEnet: SHSU::BED_GDG College of Business Administration Voice: (409) 294-1266 P. O. Box 2118 FAX: (409) 294-3612 Sam Houston State University Internet: bed_gdg@SHSU.edu Huntsville, TX 77341 bed_gdg%SHSU.decnet@relay.the.net %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% ================================================================================ Archive-Date: Sun, 24 Jan 1993 22:40:24 CST Date: Sun, 24 Jan 93 21:37:04 MST From: gilligan@central.bldrdoc.gov (Jonathan M. Gilligan) Reply-To: LitProg@SHSU.edu Message-ID: <9301250437.AA24484@central.bldrdoc.gov> To: LitProg@SHSU.edu Subject: A programmer's first use of Literate Programming George D. Greenwade writes about the need to make managers more aware of the benefits of literate programming as a tool to enhance the efficiency of programmers. While I am a novitiate being converted to LitProg in my own programming, I fear that for people who have different concerns than mine will not agree with its benefits. (I am a scientist and I'm always most concerned that my programs produce the correct results---hence LitProg extends what I've always tried to do in my comments: to make sure that I document exactly what I think I'm doing so that years later, when I discover an anomalous result I can understand what I thought I was doing and whether the problem arises from implementing my strategy incorrectly or from using a flawed strategy. The ability to typeset equations is that much more of a blessing.) I fear that after looking at many of the extant Literate Programs (TeX, METAFONT, bibTeX, etc.) one might conclude that to do literate programming, she must first rewrite all the systems libraries and stuff the rewritten routines into each literate program. (Why are the basic character I/O routines present in TeX, METAFONT, and bibTeX rather than stuffed into a library? This repetition of identical source code in three different programs seems like something that would make errors more likely since there is now the added problem that when one program is updated, it is out of synch with the others. Also, this kind of thing could cost more money, since now the programmer must spend more time keeeping the three programs synchronized. The kludges that are necessary to keep common.w and common.h in CWEB synchronized (there is no mechanism to handle changes to included files and according to Silvio Levy, there are some bugs in wmerge; and there is no mechanism to have a web file output another web file containing declarations and prototypes---this feature would be a great boon to program maintenance) illustrate the difficulties that emerge in writing a small suite of related programs in the current literate style. Clearly literate programming needs to evolve significantly if it is to achieve the status of many of the other popular methods that have come along. I think that every zealot of LP should read carefully the criticism of Knuth's word-frequency program from the Programming Pearls column. There is a lot of merit in that criticism and LP devot\'es should pay attention. However, thanks to Knuth and Levy (and others like Krommes and Ramsey) there is a solid foundation on which to experiment and build. By confining my attention to some things I see as deficits to LP tools, I do not mean to denigrate them---there are many good tools; I just think that their merits are evident to most of the readers of this list and do not need to be repeated. Personally, I am particularly fond of CWEB even with the blemishes I have mentioned, for it is a tool of manageable complexity, so I can understand it and modify it---FWEB is just too big for me to understand in the amount of time I am willing to give it. ---Jon Disclaimer --- The government probably disagrees with my opinions. ================================================================================ Archive-Date: Mon, 25 Jan 1993 06:11:10 CST Date: Fri, 22 Jan 93 17:44:13 GMT From: Timothy Murphy Reply-To: LitProg@SHSU.edu Subject: Re: CWEB++ Sender: tim@maths.tcd.ie To: LitProg@shsu.edu Message-ID: <9301221744.aa29060@salmon.maths.tcd.ie> > How can one obtain the latest copy of CWEB++ ? You could try writing to Silvio Levy . (Just going into my deepest bunker to avoid Silvio's long-range missiles ...) Timothy Murphy e-mail: tim@maths.tcd.ie tel: +353-1-2842366 (home/office) +353-1-7021507 (university) fax: +353-1-2842295 s-mail: School of Mathematics, Trinity College, Dublin 2, Ireland ================================================================================ Archive-Date: Mon, 25 Jan 1993 08:05:02 CST Date: Mon, 25 Jan 93 15:01:44 +0100 From: marcus@x4u.desy.de (Marcus Speh) Reply-To: LitProg@SHSU.edu Message-ID: <9301251401.AA17318@x4u.desy.de> To: LitProg@SHSU.edu Subject: A programmer's first use of Literate Programming References: <00967181.9C6234C0.25630@SHSU.edu> <9301250437.AA24484@central.bldrdoc.gov> CC: "John A. Krommes" >>>>> On Sun, 24 Jan 93 21:37:04 MST, Jonathan M. Gilligan said: > Personally, I am particularly fond of CWEB even with the blemishes > I have mentioned, for it is a tool of manageable complexity, > so I can understand it and modify it---FWEB is just too big for me > to understand in the amount of time I am willing to give it. I agree with most of the other statements by Jonathan. I do not agree with his statement on FWEB being "just too big": FWEB is built on CWEB. Due to excellent support by John Krommes, it has evolved into a very stable tool. If you do not insist on modifying it, there is no need to "understand" more of FWEB than of CWEB. I stick to my previous statement on this list that it won't take you more than 10 days to get used to FWEB [provided that you do not have to learn [La]TeX, your programming language of choice, nor how to use an operating system]. Moreover, for people who want to program in C++/Fortran-77 [-90]/ratfor, there is no alternative (yet). I know there are other tools who may, in principle, be adapted to any programming language, but I am thinking of someone who'd like to start right away without extensive hacking. It is true that FWEB has a richness of structure which is apt to confuse the novice. He should keep in mind thought that there's no reason (besides sheer curiosity) why he shouldn't restrict himself to a small number of features. These will suffice to use FWEB e.g. for better bookkeeping/documentation and program-formatting and thereby satisfy a user's basic needs. While your needs grow along with your skills, you may take advantage of FWEB's superiority, since FWEB has many features built-in which are not shared by other WEB tools. --Marcus Speh -- ps. Nevertheless, we're waiting for a volunteer to assemble the cweb-faq ;-) ------------------------------------------------------------------------ FWEB has got a list of Frequently Asked Questions on LitProg. You may obtain the latest version of this FAQ via anonymous FTP from - `niord.shsu.edu' [192.92.115.8] in directory `[FILESERV.FWEB]', - `ftp.imada.ou.dk' [129.142.128.14] in directory `/pub/faq/fweb' - `ftp.uni-stuttgart.de' [130.83.55.75] in directory `pub/soft/tex/web/fweb/FAQ'. - `lyman.pppl.gov' [192.55.106.129] in directory `/pub/fweb/faq' (Texinfo/text only) either as .texi, .dvi, .ps, .info or plain text file. ================================================================================ Archive-Date: Mon, 25 Jan 1993 11:52:39 CST Message-ID: <9301251747.AA16675@neuron.cs.tamu.edu> Date: Mon, 25 Jan 93 11:44:24 -0600 From: bart@cs.tamu.edu Reply-To: LitProg@SHSU.edu To: roger_alexander@rock.intersolv.com Subject: CWEB C++ version CC: LitProg@shsu.edu I suggest that you wait and watch for its availability. Silvio has made it quite plain that it is in testing. I think that anybody who is willing to make such a contribution like that should recieve the courtesy from us of living with his schedule for testing and releasing. In a previous message from our moderator: In the interim, Cameron Smith noted: > CWEB v2.8 was released last October, so probably the best thing for you to > do is to grab that directly from the source (labrea.stanford.edu, > 36.8.0.47). That should tide you over until next month, when CWEB v2.9++ > (featuring support for C++ and ANSI C) is released (as Silvio Levy > indicated in a previous note). I believe that v2.8 came out during the > unfortunate interval when a combination of George's illness and hardware > problems with the server prevented updating the archives, and it probably > got overlooked. The C++ support of FWEB is another alternative. Bart Childs ================================================================================ Archive-Date: Mon, 25 Jan 1993 14:03:42 CST Date: Mon, 25 Jan 93 11:54:03 PST From: lenny@hobbs.hunt.inmet.com (Lenny Goodman) Reply-To: LitProg@SHSU.edu Message-ID: <9301251954.AA00308@hobbs.hunt.inmet.com> To: LitProg@SHSU.edu Subject: Re: NIORD.SHSU.EDU CC: marcus@x4u.desy.de I tried doing anonymous ftp at the above site (to get FAQ), using name "anonymous" and also "guest" and using a password which was the same as the user-name; but I couldn't connect. Could you tell me the right user-name and password to use. Thanks. -- Len Goodman ================================================================================ Archive-Date: Mon, 25 Jan 1993 15:51:51 CST Date: Mon, 25 Jan 1993 15:49:58 CST From: "George D. Greenwade" Reply-To: LitProg@SHSU.edu To: LitProg@SHSU.edu CC: lenny@hobbs.hunt.inmet.com, marcus@x4u.desy.de Message-ID: <00967250.D476BD20.29260@SHSU.edu> Subject: Re: NIORD.SHSU.EDU On Mon, 25 Jan 93 11:54:03 PST, Lenny Goodman posted: > I tried doing anonymous ftp at the above site (to get FAQ), using name > "anonymous" and also "guest" and using a password which was the same as the > user-name; but I couldn't connect. Could you tell me the right user-name > and password to use. The host name is Niord.SHSU.edu (casing shouldn't matter, at least as far I am aware) and the IP address is 192.92.115.8. The username "anonymous" is supported (and since it is a VMS platform, casing positively doesn't matter) and we strongly prefer for you to use your real username as your password (we keep a log of activity and know what your IP address is when you connect; your password in this case ought to be something along the lines of lenny). The username "guest" is not supported (unless someone's been messing around with something and I'm unaware of it). Oh, about that activity log, no one ever really looks at it, except to track traffic, so you needn't worry about it (gotta keep the internal auditor happy). 8-) My suspicion is (a) you were unable to connect due to a DNS problem (i.e., a line drop for some reason) or (b) there were already too many anonymous ftp users logged in and you were bumped (we don't have a message to tell you about that -- sorry -- we can only handle 50 anonymous users at any point in time and we've been near that almost every day recently). Looking forward to the final installation of the T1 line, George %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% George D. Greenwade, Ph.D. Bitnet: BED_GDG@SHSU Department of Economics and Business Analysis THEnet: SHSU::BED_GDG College of Business Administration Voice: (409) 294-1266 P. O. Box 2118 FAX: (409) 294-3612 Sam Houston State University Internet: bed_gdg@SHSU.edu Huntsville, TX 77341 bed_gdg%SHSU.decnet@relay.the.net %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% ================================================================================ Archive-Date: Mon, 25 Jan 1993 17:10:14 CST From: Timothy Murphy Reply-To: LitProg@SHSU.edu Subject: Re: CWEB C++ version To: LitProg@shsu.edu Date: Mon, 25 Jan 93 23:04:38 GMT Sender: tim@maths.tcd.ie Message-ID: <9301252304.aa08736@salmon.maths.tcd.ie> > I suggest that you wait and watch for its availability. > Silvio has made it quite plain that it is in testing. Has he made it clear? Several people wrote to me when I posted the tiny changes to the (unposted, unofficial, unrecognised) CWEB2.9++ necessary for Borland-C, asking me how I heard of it. > I think > that anybody who is willing to make such a contribution like > that should recieve the courtesy from us of living with his > schedule for testing and releasing. I agree that we all owe Silvio gratitude for what he has done, and is continuing to do. I don't agree with the courtesy thing (as your late President would say). When a beta-version of software is announced, there is an obligation IMHO to circulate the public version with minimal delay. For one thing, I imagine many LitProggers are wondering like me about the relative merits of CWEB and FWEB for C++; so the CWEB++ announcement puts a sort of embargo on FWEB. The great selling point of CWEB lies in those magic initials, DEK. Sadly, perhaps, I don't believe any other version of WEB is likely to make it in the outside world (outside TeXland, I mean). Almost all the interest in WEB, and Literate Programming, in the universe at large arises from its association with Knuth and with TeX. For this reason CWEB carries much more weight than just another version of WEB. It carries the Nihil Obstat, or Imprimatur, of our Pope. > In a previous message from our moderator: > > In the interim, Cameron Smith noted: > > CWEB v2.8 was released last October, so probably the best thing for you to > > do is to grab that directly from the source (labrea.stanford.edu, > > 36.8.0.47). That should tide you over until next month, when CWEB v2.9++ > > (featuring support for C++ and ANSI C) is released (as Silvio Levy > > indicated in a previous note). When was this posted? Which month is next month? Timothy Murphy e-mail: tim@maths.tcd.ie tel: +353-1-2842366 (home/office) +353-1-7021507 (university) fax: +353-1-2842295 s-mail: School of Mathematics, Trinity College, Dublin 2, Ireland ================================================================================ Archive-Date: Mon, 25 Jan 1993 17:12:31 CST Date: Mon, 25 Jan 93 20:53:46 GMT Message-ID: <9836@apusapus.demon.co.uk> From: tfj@apusapus.demon.co.uk (Trevor Jenkins) Reply-To: LitProg@SHSU.edu To: LitProg@shsu.edu Subject: Re: RE: A programmer's first use of Literate Programming In message <00967181.9C6234C0.25630@SHSU.edu> George Greenwade comments upon a part of my earlier posting: > > My boss wont apprecaite the use of CWEB. My current boss wasn't one of > > those who hear DEK speak indeed they dont even know how to program, they'll > > only see that the task is complete. It'll be seen as an unecessary > > complication! But I'll know that the code is solid and that it'll work > > properly even in the presence of incorrect data. The customer will be > > unaware as well. > > This is exactly where Literate Programming needs to be developed! If my > understanding of what the WEB-type family of tools is correct, Literate > Programming is very likely the most economic way of writing available to > date. We (on this list) are rational people, unfortunately, my boss appears not to be. The use of an argument such as the one that you suggest would be seen as specious to them! Me, I'll use WEB anyway because I am convinced of the argument. I've tried to get them to realise that expending a little bit of effort now in order to same time in the future is well worth-while is only greeted with "we dont do that sort of thing"! This has been a somewhat personal comment but this is the sort of up-hill fight that us Literate Programmers must contend with. On more exciting things I've got some other comments upon the use of WEB which I'll write up at the end of the week (which ought to be the end of the project) so that a fuller picture can be had. I just wish that I could provide quantative data rather than qualative assessments. Regards, Trevor. --------------------------------------------------------------------------- Trevor Jenkins Re: "deemed!" 134 Frankland Rd, Croxley Green, Rickmansworth, WD3 3AU, England email: tfj@apusapus.demon.co.uk radio: G6AJG phone: +44 (0)923 776436 ================================================================================ Archive-Date: Mon, 25 Jan 1993 17:29:09 CST From: Timothy Murphy Reply-To: LitProg@SHSU.edu Subject: Re: A programmer's first use of Literate Programming To: LitProg@shsu.edu Date: Mon, 25 Jan 93 23:22:33 GMT Sender: tim@maths.tcd.ie Message-ID: <9301252322.aa09284@salmon.maths.tcd.ie> > Why are the > basic character I/O routines present in TeX, METAFONT, and bibTeX > rather than stuffed into a library? This repetition of identical > source code in three different programs seems like something that > would make errors more likely since there is now the added problem > that when one program is updated, it is out of synch with the others. > Also, this kind of thing could cost more money, since now the > programmer must spend more time keeeping the three programs > synchronized. Surely this was a necessary consequence of the choice of Pascal? At the time when TeX was translated from SAIL to Pascal, at least (I don't know if this is still true of official Pascal) there was no such thing as a Pascal library -- a Pascal program was a single indivisible monstrosity. Actually, WEB did meet this problem to some extent, as quite large globs of code were carried wholesale from one program to another. But doesn't Levy's CWEB answer your point completely? His common.w (shared by ctangle and cweave) serves exactly the need you describe. Timothy Murphy e-mail: tim@maths.tcd.ie tel: +353-1-2842366 (home/office) +353-1-7021507 (university) fax: +353-1-2842295 s-mail: School of Mathematics, Trinity College, Dublin 2, Ireland ================================================================================ Archive-Date: Tue, 26 Jan 1993 03:31:02 CST Message-ID: <9301260729.AA27507@math.berkeley.edu> To: LitProg@shsu.edu Subject: Re: CWEB C++ version CC: levy@geom.umn.edu Date: Mon, 25 Jan 93 23:29:21 -0800 From: Silvio Levy Reply-To: LitProg@SHSU.edu In response to various comments made about beta versions of cweb. The next release of cweb will be 3.0 (essentially the same as 2.9++, which has been in testing but hasn't been released). We expect to release it in mid-February, but there is no guarantee. People interested in testing the beta version are welcome to do so. They should write to me and I'll send it to them. "Beta testing" means actually testing, ie. finding shortcomings. (Bug fixes are most appreciated.) The release of cweb 3.0 is not meant to discourage the use of FWEB. Silvio Levy ================================================================================ Archive-Date: Tue, 26 Jan 1993 03:56:50 CST From: Joachim Schrod Reply-To: LitProg@SHSU.edu Message-ID: <9301260951.AA17286@spice.iti.informatik.th-darmstadt.de> Subject: Re: CWEB C++ version To: LitProg@SHSU.edu Date: Tue, 26 Jan 1993 10:51:45 +0100 (MEZ) Timothy Murphy wrote: > > > I think > > that anybody who is willing to make such a contribution like > > that should recieve the courtesy from us of living with his > > schedule for testing and releasing. > > I agree that we all owe Silvio gratitude for what he has done, > and is continuing to do. > I don't agree with the courtesy thing (as your late President would say). > When a beta-version of software is announced, > there is an obligation IMHO to circulate the public version > with minimal delay. IMHO: Jargon. Acronym for In My Humble Opinion. Used to flag as an opinion something that is clearly from context an opinion to everyone except the mentally dense. Opinions flagged by IMHO are actually rarely humble. IMHO. (source: third unabridged dictionary of chuqui-isms). [Chuq Von Rospach] There is *never* an obligation associated with free software. Except in the eyes of arrogant people, who don't care that others who spent work on free software have also other things to do. As long as you don't pay for it: shut up. -- Joachim ================================================================================ Archive-Date: Tue, 26 Jan 1993 10:33:46 CST From: Timothy Murphy Reply-To: LitProg@SHSU.edu Subject: Re: CWEB C++ version To: LitProg@shsu.edu Date: Tue, 26 Jan 93 16:29:44 GMT Sender: tim@maths.tcd.ie Message-ID: <9301261629.aa19190@salmon.maths.tcd.ie> > There is *never* an obligation associated with free software. Except > in the eyes of arrogant people, who don't care that others who spent > work on free software have also other things to do. > As long as you don't pay for it: shut up. I doubt very much if Silvio Levy shares your viewpoint; I know Don Knuth does not. Philanthropy _does_ in fact create an obligation on the part of both giver and receiver. "The quality of mercy is not strained ..." Thank goodness the pillars of TeX -- among whom I would include Levy, with Knuth, Lamport, Shoepf, Rokicki, Jones, MacKay, Greenwade, Berry, etc, etc -- don't take your legalistic and utilitarian attitutude. I regard TeX, like GNU, as evidence that there does exist a valid view of the world beyond that so inelegantly expressed in your final remark. Timothy Murphy e-mail: tim@maths.tcd.ie tel: +353-1-2842366 (home/office) +353-1-7021507 (university) fax: +353-1-2842295 s-mail: School of Mathematics, Trinity College, Dublin 2, Ireland ================================================================================ Archive-Date: Tue, 26 Jan 1993 11:13:14 CST Date: Tue, 26 Jan 93 10:08:05 MST From: gilligan@central.bldrdoc.gov (Jonathan M. Gilligan) Reply-To: LitProg@SHSU.edu Message-ID: <9301261708.AA09135@central.bldrdoc.gov> To: LitProg@SHSU.edu Subject: A programmer's first use of Literate Programming Timothy Murphy writes: > Why are the > basic character I/O routines present in TeX, METAFONT, and bibTeX > rather than stuffed into a library? This repetition of identical > source code in three different programs seems like something that > would make errors more likely since there is now the added problem > that when one program is updated, it is out of synch with the others. > Also, this kind of thing could cost more money, since now the > programmer must spend more time keeeping the three programs > synchronized. But doesn't Levy's CWEB answer your point completely? His common.w (shared by ctangle and cweave) serves exactly the need you describe. CWEB does answer the need somewhat (although note my cavils about the difficulty of working with change files for common.h and the fact that life would be nicer if there were a tool that would let us generate common.h directly from common.w). However, my point was not that the problem I mentioned in the paragraph above was irremediable, but that a manager looking at LitProg as a possible methodology [1] might look at examples of how LitProg was used and {\em erroneously\/} conclude that this kind of wholesale repetition was inherent to LitProg. I call upon the LitProg community to provide better examples of Literate Programming. It would be hard to improve on Knuth's skill as a programmer, but surely we can stand on his shoulders and write code in a less Proustian fashion (For a long time, Pascal used to choke on seven-bit characters...)! I conclude with a paraphrase of Strunk and White: eliminate redundant code, eliminate redundant code, eliminate redundant code. For my part, I'm trying to get used to LitProg by rewriting in CWEB a curve-fitting program I wrote in grad school. When (and if) I finish it I'll make it public for criticism. CWEB, of course is a good step in the right direction, but Literate Programming as a method applied to writing tools to do Literate Programming is rather like meditating on one's navel (Let us remember why the LitProg column in CACM folded). We need more examples of good literate programs that accomplish real tasks (i.e., that are not simply tools to write literate programs). If many people would supply code for real literate programs, we could see a diversity of styles emerge and let these inform our own. (Kudos to Cameron Smith, BTW, for a step in the right direction for giving us a nice example (although of a toy program) of multimodule programming under CWEB). [1] Language query: I've always hated the work ``methodology,'' as it seems to me that it would more appropriately describe a science that studies methods {\em qua\/} methods---why, then, are so many people, including myself, unable to break ourselves of the habit of using this ungainly word when we really mean ``method,'' but don't find that simple word sufficiently pretentious? Nonetheless, the stuffiness of the word seems appropriate when discussing managers who tell their underlings how to think about writing code ;-) ---Jon Disclaimer --- The government probably disagrees with my opinions. ================================================================================ Archive-Date: Tue, 26 Jan 1993 11:46:33 CST Date: Tue, 26 Jan 93 18:41:57 +0100 From: marcus@x4u.desy.de (Marcus Speh) Reply-To: LitProg@SHSU.edu Message-ID: <9301261741.AA05221@x4u.desy.de> To: LitProg@SHSU.edu Subject: Re: Philonous and Malevolent References: <9301212220.AA21837@tabaqui> dak> Oops, wrong subject. Not quite: this is Philonous answering. Along with the usual superfluous portion of (this time, editor) evangelism. dak> Well, how am I supposed to know what this third brace from the bottom in dak> this small, only 2-page procedure, belongs to, so that I know what the if dak> before that is about? Hmmmm, interesting. The editor I'm using (GNU Emacs) possesses a (language) mode (for c++, c, fortran, ada, lisp, ....etc.) which, upon inserting a brace, invokes (for C++ e.g.) the function c++-electric-brace Function: Insert character and correct line's indentation. If the matching brace is still in the visible part of the buffer, the cursor jumps back and forth, otherwise it tells me which line precedes the matching other brace. dak> Does she know the >> and << commands from vi? Oh, she uses them all the dak> time? Appealing. Having seen that, the question remains: who's using vi ?---There is another ongoing discussion between Malevolent and Philonous on the superior editor, but I think we can dispense with it. Needless to say that Philonous is using Mark Motl's superior web-mode for GNU Emacs. Want to know more? @-> fweb-faq, Question [18]. --Marcus Speh -- ----------------------------------------------------------------------- FWEB has got a list of Frequently Asked Questions (FAQ) for LitProg: You may obtain the latest version of this FAQ via anonymous FTP from - `niord.shsu.edu' [192.92.115.8] in directory `[FILESERV.FWEB]', - `ftp.imada.ou.dk' [129.142.128.14] in directory `/pub/faq/fweb' - `ftp.uni-stuttgart.de' [130.83.55.75] in directory `pub/soft/tex/web/fweb/FAQ'. - `lyman.pppl.gov' [192.55.106.129] in directory `/pub/fweb/faq' (Texinfo/text only) either as .texi, .dvi, .ps, .info or plain text file. ----------------------------------------------------------------------- ================================================================================ Archive-Date: Tue, 26 Jan 1993 12:46:43 CST Date: Tue, 26 Jan 93 11:42:07 MST From: gilligan@central.bldrdoc.gov (Jonathan M. Gilligan) Reply-To: LitProg@SHSU.edu Message-ID: <9301261842.AA09862@central.bldrdoc.gov> To: LitProg@shsu.edu Subject: Re: CWEB C++ version Timothy Murphy writes, > I agree that we all owe Silvio gratitude for what he has done, > and is continuing to do. > I don't agree with the courtesy thing (as your late President would say). > When a beta-version of software is announced, > there is an obligation IMHO to circulate the public version > with minimal delay. Actually, if beta testing is really testing (and Levy says that he does mean testing) then it would be silly to make the beta test period so short that there is a good chance that there will be serious problems that don't get caught until the new version is officially released. I applaud Levy for realizing that testing takes time. With good fortune, we will get a CWEB 3.0 whenever Levy and Knuth think it's ready and in return for our patience, we will be able to use it confident that version 3.1 will not need to be rushed out a few months later (as has happened with many software packages I have paid money for). It is especially important, if we are serious about converting people to Literate Programming, that Literate Programming tools written by the gurus of Literate Programming be completely bug free :-). After all, how will I convince someone of the advantages of Literate Programming if he is able to say, ``If LP is so good, why were there so many bugs in CWEB 3.0, which had the imprimatur of Knuth? If Knuth and Levy can't write bug-free software using LP, how is it going to help mere mortals like you amd me?'' Meanwhile, if you really need to use C++, FWEB is an option, and so is Hans Hermann Bode's CWEB-P, based on CWEB 2.7. ---Jon Disclaimer --- The government probably disagrees with my opinions. ================================================================================ Archive-Date: Tue, 26 Jan 1993 14:32:03 CST Date: Tue, 26 Jan 93 15:22:02 -0500 From: adnan@odin.icd.ab.com (Adnan C. Yaqub) Reply-To: LitProg@SHSU.edu Message-ID: <9301262022.AA19437@odin.icd.ab.com> To: LitProg@SHSU.edu Subject: Editing Tools (was RE: Philonous and Malevolent) >>>>> On Thu, 21 Jan 93 23:20:05 +0100, dak@POOL.informatik.rwth-aachen.de said: dak> Oops, wrong subject. Well one obvious argument for webs over small, well dak> documented routines is especially nice: Ask the offender, who hopefully dak> believes in small routines, how often it has happened that she wished the dak> measure of indents was smaller than 8 because her lines wrapped dak> when correctly indenting. Oh, she indents only 4? How is one supposed dak> to immediately see what belongs together? Oh, use a ruler? dak> Well, how am I supposed to know what this third brace from the bottom in dak> this small, only 2-page procedure, belongs to, so that I know what the if dak> before that is about? Hmmmm, interesting. dak> Does she know the >> and << commands from vi? Oh, she uses them all the dak> time? Appealing. dak> Obviously, anybody who gets along that great does not need LitProg. Although I am becoming a LitProg fan, I don't buy any of this argument. You see, I use GNU Emacs. (Maybe she does too.) I never have trouble determining what goes with what and I have my `C' indent set at 2 spaces. Adnan Yaqub (adnan@icd.ab.com) Allen-Bradley Company, Inc., 747 Alpha Drive, Highland Hts., OH 44143, USA Phone: +1 216 646 4670 FAX: +1 216 646 4484 ================================================================================ Archive-Date: Tue, 26 Jan 1993 17:39:34 CST Message-ID: <199301262323.AA27552@mucket.vast.unsw.edu.au> To: LitProg@SHSU.edu CC: stevea@vast.unsw.edu.au Subject: Re: CWEB C++ version Date: Wed, 27 Jan 93 10:23:54 +1100 From: stevea@vast.unsw.edu.au Reply-To: LitProg@SHSU.edu tim> I agree that we all owe Silvio gratitude for what he has done, tim> and is continuing to do. I don't agree with the courtesy thing tim> (as your late President would say). When a beta-version of tim> software is announced, there is an obligation IMHO to circulate tim> the public version with minimal delay. Well, in factual act, Silvio only announced that CWEB++ was in alpha testing, and did so only to let people know that CWEB was still under development. I would think it foolish if anyone wanted alpha versions of software to be released to the public. I also consider it a bit foolish to make the beta release fully available lest the public consider it an official release (come on - how many people have you come across that really don't know what alpha and beta releases are?). Additionally, Silvio has the responsibility of showing the code to DEK prior to releasing it, after all, DEK's name is very closely associated with it, and he should be allowed to veto the release if he desires. cheers -steve ================================================================================ Archive-Date: Wed, 27 Jan 1993 03:41:49 CST Date: 27 Jan 93 04:33:45 EST From: John Nesbitt <74020.3552@CompuServe.COM> Reply-To: LitProg@SHSU.edu To: Subject: CWEB++ Discussion Message-ID: <930127093345_74020.3552_EHA27-1@CompuServe.COM> I read the back and forth concerning the release of the new version of CWEB++ with mounting dismay. In a previous life, I released 'free' software. This was transaction processing software which was widely used and depended upon within a particular community. I NEVER felt any legal obligation vis-a-vis release dates and features. I did, however, feel a strong moral obligation to the users of my programs to fix bugs, to add useful features and to release reliable programs. I learned through bitter experience to be extremely careful in releasing beta versions: these things acquire a life of their own. It is time-consuming enough to support the 'official' release without getting calls about old beta versions. It is a truism that software versions are never released on time. In the commercial world which I inhabit, one is paying real money and often has the option of selecting a different vendor (but not always: everybody is late). In the world of 'free' software, I think that one pays in the coin of patience and understanding for the developer, who doubtless has many other things on his plate. On a more general note, I am distressed at the amount of flaming in this discussion. This is unfortunate and truly unnecessary. To paraphrase: abuse is the last resort of somebody with a bad argument. John Nesbitt, Geneva ================================================================================ Archive-Date: Wed, 27 Jan 1993 05:06:45 CST Date: Wed, 27 Jan 93 11:59:39 +0100 From: dak@POOL.informatik.rwth-aachen.de Reply-To: LitProg@SHSU.edu Message-ID: <9301271059.AA00486@hathi> To: LitProg@SHSU.edu Subject: Re: Editing Tools (was RE: Philonous and Malevolent) >>>>>> On Thu, 21 Jan 93 23:20:05 +0100, dak@POOL.informatik.rwth-aachen.de said: >dak> Oops, wrong subject. Well one obvious argument for webs over small, well >dak> documented routines is especially nice: Ask the offender, who hopefully >dak> believes in small routines, how often it has happened that she wished the >dak> measure of indents was smaller than 8 because her lines wrapped >dak> when correctly indenting. Oh, she indents only 4? How is one supposed >dak> to immediately see what belongs together? Oh, use a ruler? > >dak> Well, how am I supposed to know what this third brace from the bottom in >dak> this small, only 2-page procedure, belongs to, so that I know what the if >dak> before that is about? Hmmmm, interesting. > >dak> Does she know the >> and << commands from vi? Oh, she uses them all the >dak> time? Appealing. > >dak> Obviously, anybody who gets along that great does not need LitProg. > >Although I am becoming a LitProg fan, I don't buy any of this >argument. You see, I use GNU Emacs. (Maybe she does too.) I never >have trouble determining what goes with what and I have my `C' indent >set at 2 spaces. > >Adnan Yaqub (adnan@icd.ab.com) Thanks for making my argument abundantly clear. If you need a special editor mode just to find out what belongs where, you are doing write-only code, and your listings will not necessarily reveal the structure on editor-free reading. If your C indent has wandered to merely 2 spaces, you are very likely not to see the indenting structure when reading a listing, at least not without a ruler. I was not arguing for complications in writing code, I was arguing for the readability. And I had brought vi into the discussion, because I wanted to point out that the use of >>, and <<, as well as reducing indenting to 4, serves to make highly indented, and thus not readily understandable when only skimming, code. That you scoff on the primitivity of the features by vi, and tell me Emacs does it better, is a sign that you have not got my point. I was blaming the need to use that features, not the inadequacies of them. I do not want to have to use a tool merely to read some code. I want a printout to be understandable as well. That you have not even got my point is a dangerous sign, because it implies that programmers take write-only code with high level of small indentation for granted, and worry only about how they can produce that with the least effort. ================================================================================ Archive-Date: Wed, 27 Jan 1993 05:08:06 CST Date: Wed, 27 Jan 93 02:08:24 GMT Message-ID: <9989@apusapus.demon.co.uk> From: tfj@apusapus.demon.co.uk (Trevor Jenkins) Reply-To: LitProg@SHSU.edu To: LitProg@shsu.edu CC: tfj@apusapus.demon.co.uk Subject: Page 1 is (almost) entirely blank When I run my CWEB source file through CWEAVE (2.7 [pl6]) and then through TeX page 1 is ``blank''. (Actually it has the page number and the page heading "CWEB output" and the word from the \ttitlefont call abutted to the entire text of the \title call.) Is this correct behaviour? I encountered another oddity with the same TeX run. At one point in my source code I have the following construct \.{message("! usage: MARCIT [-options] MARC_file [TFORM_file [report_file]]" ..} TeX bitches that there's a missing $ sign missing and indicates the _. All other use of _ are accepted okay so why not here? Regards, Trevor. --------------------------------------------------------------------------- Trevor Jenkins Re: "deemed!" 134 Frankland Rd, Croxley Green, Rickmansworth, WD3 3AU, England email: tfj@apusapus.demon.co.uk radio: G6AJG phone: +44 (0)923 776436 ================================================================================ Archive-Date: Wed, 27 Jan 1993 05:15:39 CST Date: Wed, 27 Jan 93 12:11:32 +0100 From: dak@POOL.informatik.rwth-aachen.de Reply-To: LitProg@SHSU.edu Message-ID: <9301271111.AA00675@hathi> To: LitProg@SHSU.edu Subject: Re: Philonous and Malevolent >dak> Oops, wrong subject. > >Not quite: this is Philonous answering. Along with the usual >superfluous portion of (this time, editor) evangelism. Sorry, but you missed my point. I was not fighting for vi's right to be the best editor for writing unreadable code. > >dak> Well, how am I supposed to know what this third brace from the bottom in >dak> this small, only 2-page procedure, belongs to, so that I know what the if >dak> before that is about? Hmmmm, interesting. > >The editor I'm using (GNU Emacs) possesses a (language) mode (for c++, >c, fortran, ada, lisp, ....etc.) which, upon inserting a brace, >invokes (for C++ e.g.) the function > > c++-electric-brace > Function: Insert character and correct line's indentation. > >If the matching brace is still in the visible part of the buffer, >the cursor jumps back and forth, otherwise it tells me which line >precedes the matching other brace. Congratulations. So even if the structure of your code is incomprehensible, you have a good chance of getting it to compile. Shit, I was not worrying about producing something the compiler would not understand. I was hoping for the humans. > >dak> Does she know the >> and << commands from vi? Oh, she uses them all the >dak> time? Appealing. > >Having seen that, the question remains: who's using vi ?---There is >another ongoing discussion between Malevolent and Philonous on the >superior editor, but I think we can dispense with it. Especially since this discussion was not about editors. >Needless to say >that Philonous is using Mark Motl's superior web-mode for GNU Emacs. Want >to know more? @-> fweb-faq, Question [18]. If Philonous is using Mark Motl's superior Webmode in order to produce highly indented, thoroughly nested code, he need not use a web at all. ================================================================================ Archive-Date: Wed, 27 Jan 1993 07:31:16 CST Date: Wed, 27 Jan 93 07:26:56 CST From: bart@cs.tamu.edu (Bart Childs) Reply-To: LitProg@SHSU.edu Message-ID: <9301271326.AA11383@neuron.cs.tamu.edu> To: LitProg@shsu.edu Subject: Re: Page 1 is (almost) entirely blank Trevor Jenkins has run into a common pain for starting WEB'ers. The file `limbo.material' is one of the appendages to the source of the manual for our web-mode. (We named the file webm-man.tex). I have not created a brand new CWEB in a while, but when web-mode starts up, it asks for the name of the file for limbo material to be included and defaults to that file. It then prompts for a `title' of the WEB and edits the inserted limbo material to create a proper title page. The TeX error is also commonly encountered by beginners (and sometimes by experienced users). If you include a comment in C code like: /* some_variable */ this should be written as /* |some_variable| */ because TeX reserves the underscore for the subscript character and is supposed to be used in math mode.... Hope it helps. Bart Childs ================================================================================ Archive-Date: Wed, 27 Jan 1993 09:31:19 CST Date: Wed, 27 Jan 93 09:30:17 CST From: fulling@sarastro.math.tamu.edu (Stephen A. Fulling) Reply-To: LitProg@SHSU.edu Message-ID: <9301271530.AA05232@sarastro.math.tamu.edu> To: LitProg@shsu.edu Subject: Re: CWEB++ Discussion CC: fulling@sarastro.math.tamu.edu I think that this discussion has drifted away from its original point: Last fall most of us got the impression that the release of CWEB++ was imminent; that was followed by several months of mystifying silence. Silvio Levy has now confirmed that he hopes for a release within the next month, thereby saving himself the annoyance of answering many individual inquiries, I hope. I think we all understand the problem of the moving target. Silvio has given us the information we needed, and gone back to work. I agree with J. Nesbitt that the other disputants should stifle themselves. Steve Fulling ================================================================================ Archive-Date: Wed, 27 Jan 1993 09:41:53 CST Date: 27 Jan 93 09:31:00 CST From: "Thompson, David B." Reply-To: LitProg@SHSU.edu Subject: RE: A programmer's first use of Literate Programming To: "litprog" I was amused by Jon's ruminations about the word "methodology." FWIW, I find its overuse offensive as well. Another word in this category is "utilize." Perhaps we should agree to "use" a "method" instead of utilizing a methodology? -=d ================================================================================ Archive-Date: Wed, 27 Jan 1993 10:21:04 CST Date: Wed, 27 Jan 93 17:16:08 +0100 From: Roegel Denis Reply-To: LitProg@SHSU.edu Message-ID: <9301271616.AA07892@pandore.loria.fr> To: LITPROG@SHSU.edu Subject: bad CWEB formatting (cont'ed) CC: roegel@pandore.loria.fr Two weeks ago, I had a question regarding the formatting of a variable called 'line'. Well, to format it correctly one has to do @f line foo (for instance) But, when I do this I get---in the TeX file---something broken, like that: format line foo Is this a known problem ? Is it possible to achieve the right formatting without printing the line "format line foo" ? Another problem appears in a construct like if ... else { struct timeval udate; struct tm *pdate; gettimeofday(...); ... } What I get is: if ... else {struct timeval udate; struct tm *pdate; gettimeofday(...); ... ...} (notice also the wrong positionning of the closing brace) I tried to insert @/ after the opening brace or to write @f timeval foo but it doesn't help. I'm desperately stuck! Any idea ? Thanks in advance. Denis (roegel@loria.fr) PS. And a late thank to those you pointed me to @f the last time. Sorry for the delay! ================================================================================ Archive-Date: Wed, 27 Jan 1993 15:39:37 CST Date: Wed, 27 Jan 93 15:33:45 CST From: fulling@sarastro.math.tamu.edu (Stephen A. Fulling) Reply-To: LitProg@SHSU.edu Message-ID: <9301272133.AA05317@sarastro.math.tamu.edu> To: LitProg@shsu.edu Subject: Re: A programmer's first use of Literate Programming CC: fulling@sarastro.math.tamu.edu Jonathan M. Gilligan writes: >I call upon the LitProg community to provide better examples of >Literate Programming.... For my part, I'm trying to get used to >LitProg by rewriting in CWEB a curve-fitting program I wrote in >grad school. When (and if) I finish it I'll make it public for >criticism. > >CWEB, of course is a good step in the right direction, but >Literate Programming as a method applied to writing tools to do >Literate Programming is rather like meditating on one's navel >(Let us remember why the LitProg column in CACM folded). We need >more examples of good literate programs that accomplish real tasks >(i.e., that are not simply tools to write literate programs). If >many people would supply code for real literate programs, we could >see a diversity of styles emerge and let these inform our own. >(Kudos to Cameron Smith, BTW, for a step in the right direction >for giving us a nice example (although of a toy program) of >multimodule programming under CWEB). After two years of reading about Literate Programming and thinking and talking about what a great idea it is, over the holidays I finally wrote my first literate programs. I took two short programs written 12 years ago in C and redid them in CWEB. Yes, I know that's not the way you're supposed to do it, but I wanted my first hands-on experience with CWEB syntax to be free of extraneous concerns such as correctness of algorithms. These programs "accomplish a real task": they calculate the terms in an asymptotic expansion approximating the solution of a system of differential equations. They may therefore be of interest as examples of CWEB that are not computer utilities, such as word-counting programs. They are probably short enough (7063 and 11532 bytes) to be posted directly to the list, but I doubt that George Greenwade would appreciate that precedent, so I'll ask his advice on how to make them available. The originals were the first C programs I ever wrote, in 1981. In 1987 I revised them and added copious comments; at that time I flattered myself that they were already fairly literate :-). But the cramped nature of program comments and especially the impossibility of including typeset mathematics left the explanatory material inadequate. The WEB versions produce 3 times as many printed pages, but the additional information is well worth it, I think. I hope that one can actually understand the purpose of the program now without reading the associated journal article in SIAM J. Math. Anal. Of course, I modularized the programs too (perhaps overdoing it a bit). Stephen A. Fulling Professor of Mathematics, 12 years experience as a second-order C programmer (percentage of professional life devoted to research = O(epsilon), percentage of research devoted to computation = O(epsilon)) ================================================================================ Archive-Date: Thu, 28 Jan 1993 14:46:46 CST From: Timothy Murphy Reply-To: LitProg@SHSU.edu Subject: Re: CWEB C++ version To: LitProg@shsu.edu Date: Thu, 28 Jan 93 18:07:13 GMT Sender: tim@maths.tcd.ie Message-ID: <9301281807.aa11974@salmon.maths.tcd.ie> > Additionally, Silvio has the responsibility of showing the code > to DEK prior to releasing it, after all, DEK's name is very closely > associated with it, and he should be allowed to veto the release if he > desires. I'd agree with this, at least, if in fact it is the reason for the delay. Timothy Murphy e-mail: tim@maths.tcd.ie tel: +353-1-2842366 (home/office) +353-1-7021507 (university) fax: +353-1-2842295 s-mail: School of Mathematics, Trinity College, Dublin 2, Ireland ================================================================================ Archive-Date: Thu, 28 Jan 1993 14:49:02 CST Message-ID: <9301282017.AA13682@math.berkeley.edu> To: tfj@apusapus.demon.co.uk Subject: Re: Page 1 is (almost) entirely blank CC: LitProg@shsu.edu Date: Thu, 28 Jan 93 12:17:25 -0800 From: Silvio Levy Reply-To: LitProg@SHSU.edu > When I run my CWEB source file through CWEAVE (2.7 [pl6]) and then through > TeX page 1 is ``blank''. (Actually it has the page number and the page > heading "CWEB output" and the word from the \ttitlefont call abutted to the > entire text of the \title call.) Is this correct behaviour? It doesn't sound correct, but I can't really figure out what you mean. I assume you mean the first page of the program (that is, not the title page)? Perhaps you should create a minimal file that exhibits the problem, and mail it to me. > \.{message("! usage: MARCIT [-options] MARC_file [TFORM_file [report_file]]"} The \. is only a TeX macro -- \.{foo} is the same as {\tt foo}. TeX has no way to know that _ is meant as a special character in a verbatim string. > All other uses of _ are accepted okay so why not here? I think the only time _ is treated especially (ie., not as a math subscript character) is in strings and character constants in C code. Silvio ================================================================================ Archive-Date: Thu, 28 Jan 1993 14:54:06 CST From: Thorbjoern Ravn Andersen Reply-To: LitProg@SHSU.edu Message-ID: <9301282017.AA16722@imada.ou.dk> Subject: Re: Editing Tools (was RE: Philonous and Malevolent) To: LitProg@SHSU.edu Date: Thu, 28 Jan 93 21:17:43 MET dak@POOL.informatik.rwth-aachen.de | If your C indent has wandered to merely 2 spaces, you are very likely | not to see the indenting structure when reading a listing, at least | not without a ruler. I was not arguing for complications in writing | code, I was arguing for the readability. And I had brought vi into | the discussion, because I wanted to point out that the use of >>, | and <<, as well as reducing indenting to 4, serves to make highly | indented, and thus not readily understandable when only skimming, | code. That you scoff on the primitivity of the features by vi, and | tell me Emacs does it better, is a sign that you have not got | my point. Well. I have never really figured why indenting 8 spaces (with a TAB) should make C programs that much more readable than anything else bigger than, say 2. Being a Pascal programmer reluctantly forced into C (the great assembly language of *real* machines) I have used an indentation of 2 with a very consequent way of changing it for several years. My experience shows this to be more effective than moving code back and forth horizontally on the page. And, no, I do not have bracket-matching in my editor. :-( | I was blaming the need to use that features, not the inadequacies | of them. I do not want to have to use a tool merely to read | some code. I want a printout to be understandable as well. | That you have not even got my point is a dangerous sign, because | it implies that programmers take write-only code with high | level of small indentation for granted, and worry only about how | they can produce that with the least effort. Agreed. Small identations are, however, not implying unreadable code. -- Thorbj{\o}rn Andersen ravn@imada.ou.dk ================================================================================ Archive-Date: Thu, 28 Jan 1993 15:48:58 CST Date: Thu, 28 Jan 93 16:30:54 -0500 From: figuei@lutece.rutgers.edu (Francisco Figueirido) Message-ID: <9301282130.AA07745@lutece.rutgers.edu> To: litprog@shsu.edu Subject: (commented) source code and user documentation in FWEB Reply-To: LitProg@SHSU.edu I have been using WEB (mostly FWEB) for about a year and am very happy with the results. However, I think (please send flames to my e-mail address, not to the mailing list!) that the WEB systems that exist today (actually, the ones I know) have a common problem: they cannot handle very well the users' documentation (as opposed to the programmer's documentation, that was the original purpose of WEB). I have been playing a little with the idea of using FWEB (since it is the only one that understands more than one language) to write in the same .web file both the source code web AND the user documentation. The idea, which might not be original, is to use TeX as the default language and to have in the web file code like this: ============================================================================== @ This code will be sent to the file \.{usermanual.tex}. @a @O usermanual.tex \title{MyProgram, A User Manual} This is the user manual for the wonderful program MyProgram. @ @ This code will be sent to the \Cee\ file \.{myprog.c}. @a @o myprog.c extern int main(int argc, char **argv) @+ { @ @; @ @; } . . . @ This fragment handles the command line arguments. @= while (argc-- > 0) @+ { argv++; @ @; } @ This section of \TeX\ code describes the command line arguments from a users' point of view. @= \begin{itemize} \item[-v] Be verbose . . . \end{itemize} ============================================================================== The rationale is that users (most of the time) couldn't care less about the internals of the program; they just want a digested and very high level view of how to interface with the program. And if this interface is complicated or subject to change it is not a good idea to have separate sources for the source code and the users' documentation. I would be very interested to know other people's experiences and (+ or -) comments about this embrionic proposal. A further note: it would be nice in my opinion to have another start-of-module symbol, say @w (if not in use), to mark modules as invisible to weave but not to tangle. In this way one could write the user manual code as @w This code will be sent to the file \.{usermanual.tex}. @a @O usermanual.tex and this would not appear in the woven output. This way we can separate programmer's and users' manuals while keeping them synchronized. Francisco Figueirido email: figuei@lutece.rutgers.edu phone: (908)932-3278 ================================================================================ Archive-Date: Thu, 28 Jan 1993 18:03:32 CST Date: Thu, 28 Jan 93 23:34:15 +0100 From: Roegel Denis Reply-To: LitProg@SHSU.edu Message-ID: <9301282234.AA11469@pandore.loria.fr> To: LITPROG@SHSU.edu Subject: \long string in CWEB: how ? CC: roegel@pandore.loria.fr Hello, Here is another little problem I face. As a matter of fact, I am translating some more or less old C programs into CWEB. I really love to do it, but all possible problems occur. Here is one. With the next static declaration, Cweave tells me that the string is too long. How can I override this ? static String text_translationsD = "\ Delete: DeleteD() end-of-file() delete-previous-character()\n\ BackSpace: DeleteD() end-of-file() delete-previous-character()\n\ Return: end-of-file() newline() DispatchD()\n\ : InsertD() end-of-file() insert-char()\n\ : select-start() \n\ : extend-adjust() \n\ : extend-end(PRIMARY, CUT_BUFFER0) \n\ : extend-start() \n\ : extend-adjust() \n\ : extend-end(PRIMARY, CUT_BUFFER0)"; Thanks in advance for your ideas. Denis. (roegel@loria.fr) ================================================================================ Archive-Date: Fri, 29 Jan 1993 08:18:15 CST Date: 29 Jan 1993 13:06 +0000 (GMT) From: "Eric W. van Ammers, LUW, tel: (+31)8370-83356" Reply-To: LitProg@SHSU.edu Subject: Who knows ... To: LITPROG@shsu.edu Message-ID: <01GU3BN4ELCW8WWQIX@RCL.WAU.NL> Promoting Literate Programming I'm trying to promote literate programming, but unfortunately I live in a hostile environment. So I need hard arguments. It would be an enormous help if I had reports on (controlled) experiments with literate programming. For example like the one of Ramsey and Marceau Literate Programming on a Team Project Softw.Pract.&Exp. 21, 7, 677-683 (July 1991). Also references to discussions on the merits of LP are welcome, as long as they are in refereed journals. Of course I already have the Literate Programming columns of CACM. Eric W. van Ammers (ammers@rcl.wau.nl) ================================================================================ Archive-Date: Fri, 29 Jan 1993 11:21:12 CST Date: Fri, 29 Jan 93 18:07:10 +0100 From: coates@spectro.jussieu.fr Reply-To: LitProg@SHSU.edu Message-ID: <9301291707.AA15523@lutidine.spectro.jussieu.fr> To: LitProg@shsu.edu Subject: Indent spacing Dear Tony, On the subject, floating around of late, of the correct indent to use for source code (C or C++ usually, for me), I have to say that I find 1 tab = 8 spaces to be too much, if one has a few levels of indenting. There's no space left for the code on the end of the line! I use two spaces between levels, and even then I keep asking myself if that isn't one space too many. To avoid losing track of indenting levels, I prefer to use a system like if (condition) { ... } /* end if (condition) */ to clearly mark which closing construct goes with which opening construct. With this system, I find two spaces of indent per level to be quite enough. This is the bottom-end of "Literate Programming", I suppose, but that's my 2c worth anyway. Cheers, Tony. ________________________________________________________________________________ A.B.Coates (Tony) Laboratoire de Spectroscopie Hertzienne de l'ENS Universite Pierre et Marie Curie Case 74, 4 place Jussieu Email: coates@spectro.jussieu.fr F-75252 Paris CEDEX 05 Telephone: +33 1 44 27 44 09 France Fax: +33 1 44 27 38 45 "J'ai mes opinions. L'universite a ses opinions. L'intersection de ces deux ensembles est probablement vide." "I have my opinions. The university has its opinions. The intersection of these two sets is probably empty." ________________________________________________________________________________ ================================================================================ Archive-Date: Fri, 29 Jan 1993 11:46:56 CST Message-ID: <9301291740.AA28992@math.berkeley.edu> To: LitProg@shsu.edu Subject: Re: \long string in CWEB: how ? CC: roegel@pandore.loria.fr, levy@geom.umn.edu Date: Fri, 29 Jan 93 09:40:20 -0800 From: Silvio Levy Reply-To: LitProg@SHSU.edu Here is one kludge that will work for very long strings. @ \begingroup % temporarily redefine the way @& and @= print. \def\J{\hfil\break}\let\vb\. @c static String text_translationsD = @="\@>@& @=Delete: DeleteD() end-of-file() delete-previous-character()\n\@>@& @=BackSpace: DeleteD() end-of-file() delete-previous-character()\n\@>@& @=Return: end-of-file() newline() DispatchD()\n\@>@& @=: InsertD() end-of-file() insert-char()\n\@>@& @=: select-start() \n\@>@& @=: extend-adjust() \n\@>@& @=: extend-end(PRIMARY, CUT_BUFFER0) \n\@>@& @=: extend-start() \n\@>@& @=: extend-adjust() \n\@>@& @=: extend-end(PRIMARY, CUT_BUFFER0)"@>; @ \endgroup ================================================================================ Archive-Date: Fri, 29 Jan 1993 13:26:10 CST Message-ID: <9301291913.AA21889@im4u.cs.utexas.edu> From: leew@cs.utexas.edu (Lee Wittenberg) Reply-To: LitProg@SHSU.edu Date: Fri, 29 Jan 1993 13:13:39 -0600 To: LitProg@shsu.edu Subject: Re: CWEB C++ version To veer slightly from the main discussion: Timothy Murphy quotes Shakespeare: "The quality of mercy is not strained ..." As Richard Armour put it: "If the quality of mercy is not strained, how is it kept from becoming lumpy?" Nothing useful to contribute this time. -- Lee ================================================================================ Archive-Date: Fri, 29 Jan 1993 13:51:21 CST Message-ID: <9301291945.AA23644@im4u.cs.utexas.edu> From: leew@cs.utexas.edu (Lee Wittenberg) Reply-To: LitProg@SHSU.edu Date: Fri, 29 Jan 1993 13:45:39 -0600 To: LitProg@shsu.edu Subject: Re: A programmer's first use of Literate Programming Jonathan M. Gilligan writes (among other things): > ... life would be nicer if there were a tool that would let us generate > common.h directly from common.w Actually, CWEB does support this directly, with the @( facility (which I make use of frequently to generate .h files for literate libraries (sic)). However, I believe that the separate common.h file dates from the early days of CWEB, before this facility was available. I believe that the idea was originally developed by Norman Ramsey for Spidery WEB, and was added to CWEB later. Personally, I would be a lot happier if common.w used @(common.h@>= to generate the common.h file. -- Lee ================================================================================ Archive-Date: Fri, 29 Jan 1993 14:13:42 CST Message-ID: <9301292004.AA25297@im4u.cs.utexas.edu> From: leew@cs.utexas.edu (Lee Wittenberg) Reply-To: LitProg@SHSU.edu Date: Fri, 29 Jan 1993 14:04:49 -0600 To: LitProg@shsu.edu Subject: Re: \long string in CWEB: how ? Roegel Denis (Denis Roegel?) writes: > Here is another little problem I face. As a matter of fact, I am > translating some more or less old C programs into CWEB. I really > love to do it, but all possible problems occur. Here is one. With the next > static declaration, Cweave tells me that the string is too long. > How can I override this ? > > static String text_translationsD = "\ > Delete: DeleteD() end-of-file() delete-previous-character()\n\ > BackSpace: DeleteD() end-of-file() delete-previous-character()\n\ > Return: end-of-file() newline() DispatchD()\n\ > : InsertD() end-of-file() insert-char()\n\ > : select-start() \n\ > : extend-adjust() \n\ > : extend-end(PRIMARY, CUT_BUFFER0) \n\ > : extend-start() \n\ > : extend-adjust() \n\ > : extend-end(PRIMARY, CUT_BUFFER0)"; For this problem I'd use a Standard C feature instead of a CWEB one. ANSI C automatically concatenates adjacent string constants (as did a number of pre-standard compilers). I'd write the above code (in CWEB) as: static String text_translationsD = @/ "Delete: DeleteD() end-of-file() delete-previous-character()\n" @/ "BackSpace: DeleteD() end-of-file() delete-previous-character()\n" @/ "Return: end-of-file() newline() DispatchD()\n" @/ ": InsertD() end-of-file() insert-char()\n" @/ " : select-start() \n" @/ " : extend-adjust() \n" @/ " : extend-end(PRIMARY, CUT_BUFFER0) \n" @/ " : extend-start() \n" @/ " : extend-adjust() \n" @/ " : extend-end(PRIMARY, CUT_BUFFER0)"; The @/s are, of course, CWEB formatting commands to put things on separate lines. @| might be better (so following lines will be indented). You may have to play around a bit to get the formatting you want. Anyway, as long as your C compiler supports the standard, you don't have to worry about CWEB's maximum string length (or the C mishegoss using \ to continue a string on the next line). -- Lee ================================================================================ Archive-Date: Fri, 29 Jan 1993 15:32:51 CST Date: Fri, 29 Jan 93 16:31:36 -0500 From: kirby!kirby!kirby@kirby Reply-To: LitProg@SHSU.edu Message-ID: <9301292131.AA03104@kirby> To: litprog@shsu.edu CC: kirby@coastal.udel.edu unsubscribe litprog for kirby@kirby.ce.udel.edu subscribe litprog kirby@coastal.udel.edu ================================================================================ Archive-Date: Fri, 29 Jan 1993 17:54:45 CST Message-ID: <9301292351.AA05907@hydrus.mc.xerox.com> To: LitProg@shsu.edu Subject: Re: Editing Tools (was RE: Philonous and Malevolent) Reply-To: LitProg@SHSU.edu Date: Fri, 29 Jan 1993 15:51:24 PST From: "Marty Leisner" In message <9301282017.AA16722@imada.ou.dk> you write: >dak@POOL.informatik.rwth-aachen.de > >Well. I have never really figured why indenting 8 spaces (with a TAB) >should make C programs that much more readable than anything else bigger >than, say 2. > >Being a Pascal programmer reluctantly forced into C (the great assembly >language of *real* machines) I have used an indentation of 2 with a very >consequent way of changing it for several years. My experience shows >this to be more effective than moving code back and forth horizontally >on the page. And, no, I do not have bracket-matching in my editor. :-( >... >Agreed. Small identations are, however, not implying unreadable code. I find code with 2 space identation a waste of my time...I thorugh such code through indent... Having a problem moving back and forth horizontally is an indication you have to many levels in one function... marty leisner@eso.mc.xerox.com leisner.henr801c@xerox.com Member of the League for Programming Freedom "People cannot be managed. Inventories can be managed, but people must be led" -- H. Ross Perot ================================================================================ Archive-Date: Fri, 29 Jan 1993 18:09:16 CST Date: Fri, 29 Jan 93 23:57:44 GMT Message-ID: <10217@apusapus.demon.co.uk> From: tfj@apusapus.demon.co.uk (Trevor Jenkins) Reply-To: LitProg@SHSU.edu To: LitProg@shsu.edu CC: tfj@apusapus.demon.co.uk Subject: A programmer's first WEB---week two This week's installment of "A programmer's first WEB". Nobody objected to last week's posting about writing my first Literate Program so I've taken the liberty of wasting more bandwidth by writing about this week's progress. I changed the experiment (as a result of last week's message) in that I kept notes during the week; last week's report was just Friday night recollections. There are three sets of goals that my experiment ought to satisfy: 1 Donald E. Knuth's. As espoused in his writings on Literate Programming. Unfortunately, I've mislaid my copy of the Computer Journal with his original paper on the subject. :-( Must be somewhere in my loft. Also, few of the London bookstore's stocked his "Literate Programming" book and even fewer are likely to re-stock it. :-(( All in all I shall refrain from saying anymore about his criteria/goals until after the project is finished. 2 My employers. As I wrote earlier this week they dont know that the experiment is being conducted; all they do know is that I'm writing the program to specification. Their goals are that the job is done with minimal effort in creating the utility and that it requires little effort to maintain it next year when the customer's data changes! 3 My own goals. I can wax lyrical about these. :-) a I wanted to use WEB (actually CWEB) on a real project. I had read DEK's paper; the stuff in Jon Bentley's "Programming Pearls" and then Van Wyck's (short-lived) "Literate Programming" column in the Comm of the ACM but now I felt it was time for me to do it myself. b The desire to use WEB was based upon my expectation of the complexity of the code. (Anyone who has ever tried to de-block a USMARC tape will understand what the problems are---because that is exactly what I'm doing.) I have to admit that I normally get ``flussered'' by the complexity of code that I've written after only a couple of hundred lines---I estimated that this conversion utility would be around 1,000 to 1,500 lines in total, ie more than I wanted to have to cope with using my old skills. So I unilaterally decided that I would write the thing using CWEB. By the way, I've gotten the tape de-blocking working and some of the USMARC to internal format working. The CTANGLEd code for which is currently just over 500 lines. I have the reports/listings code to write and possibly some other manipulations of the data will be necessary. This latter because the specification of the data on the tape is not very clear---in fact it's opaque! c Reduce the debugging time. I think that this has happened. The major problem is that I'm not a C programmer. Until this project I was always a Pascal programmer but the employers have switched to C so... It does mean that the utility can be run on a Unix box if required, in addition to the VMS box that it's targeted for. Even if the debugging time is not reduced at least I'm calmer than I would be when trying to get the beast to run using my old working methods! :-) d I wanted to see what my own literate program would be like. It's rather like the first time that I held the card deck for the first production program I wrote. A great sense of satisfaction. Summary of the week Rather than bore you all with a diary of events I want to make some observations about my usage of Literate Programming. In passing I'll make suggestions for additional tools that would have made the programming task easier. The use of Literate Programming meant that recommencing work on Monday morning was ``instantanious''. The reduction of complexity inherent in each section of code meant that I could concentrate upon specific portions that required correction and concentrate upon the specifics. The index to the listing proved invaluable to getting on with it straight away. It was easier to concentrate upon the code. Fragments of it remained in my mind longer than such things do normally. Even when I was working on fragment A, I found myself correcting fragment B and then going back to A again without loosing my train of thought. It was easy to insert new code quickly especially for a couple of things which had been forgotten. Estimating the amount of work involved was/is difficult. KDSI is inappropriate for a literate program as there are many lines of what would only be exchanged in conversations between programmers (if at all). I made the same ``slips of the pen'' that I would have made in a non-literate program. However, they came to light very quickly. Usually during a code reading. Correcting complex boolean conditions became easier, though it was still difficult to express them correctly. On a number of occasions I wanted a CWEB macro feature. Not the @d directive but rather some way to have CWEB macros for handling code that is very similar. I resorted to cut-and-paste within the editor. Any tendency to hack or patch the code could be resisted easily. Working practices A working pattern emerged very quickly. I commute to my office by London Underground which means that I get to sit down for approximately one hour before actually arriving at the office. I used this time to read through the listing in preparation for the days work. Reading the listing also took my mind of the delays in the journey---that is I arrived at my usual time...late. :-) On getting to the office I would correct the errors that I'd seen during that early morning read-through. A lot of these early-bird worms were ``speelnig misteaks''. Once these were corrected I could start on some portion of the code that had (so to speak) taking my fancy during the journey. This thinking/editing work would continue until about 15:30 when I would try to weave/tangle the web source. Once I'd corrected typing mistakes in the .w file I could try compiling the .c file. When I had a clean compilation I then ran the executable. Whilst one iteration of the edit/compile/link/test cycle takes longer with WEB I think that the cycles were more productive than before. What fascinated me was that I rarely needed to read the source code to figure out what was the problem. Because, as I said earlier, I had it all in my head I could correct the problems quickly. (Well quicker than I used to when using the non-literate programming paradigm.) Some ``negatives'' It was a mistake to add several new sections into the .w file at the same moment that I used my first change file. I nearly ``lost it'' then. However, i decided that in future I would add new sections immediately prior to the Index section until such time as I wanted/needed to generate a complete listing when I would re-organise the exposition of sections in a more instructive order. Several times I wished for a Windows-based editor. I wanted to be able to view the current section, the section in which it was used and the definition of variables and macros at the same time. Clicking on a lexeme whilst pointing at it and having all the relevant sections available wouyld have been a great doon. I remember arguing this self-same case in an examination answer during my Master's degree finals; these finals took place not long after I heard DEK's London talk. On my PC I have Microsoft's Programmer's Workbench which I used to compile CWEAVE and CTANGLE. I was impressed by the fact that during symbolic execution of the code it (PWB) honoured the #line directives. Shock and horror then to discover that VMS debug did NOT honour them!!!! My next task is to write a simple program that takes the output from the VMS DIFFERENCES utility and creates a change file. This will of course be a literate program. literate program. ================================================================================ Archive-Date: Sat, 30 Jan 1993 14:45:07 CST Date: Sat, 30 Jan 93 15:37:27 GMT Message-ID: <10244@apusapus.demon.co.uk> From: tfj@apusapus.demon.co.uk (Trevor Jenkins) Reply-To: LitProg@SHSU.edu To: LitProg@shsu.edu Subject: Re: Indent spacing In message <9301291707.AA15523@lutidine.spectro.jussieu.fr> you write: > On the subject, floating around of late, of the correct indent to use > for source code (C or C++ usually, for me), As the only (production) program that I've written in C is the Literate Program that I have been going on about for the last 10 days I haven't developed an indetation style. However, when I started my little proggie I indent the the C code within each section by three spaces. After a little while I stopped doing that even as tangle rather mangles the indentation of the .c files, I just got used to it. > I have to say that I find 1 tab = > 8 spaces to be too much, I think that a tab stop of 8 is too large. I can still picture my first sizeable Algol-68 program where I had one card with several nested if/then/else/fi occurences together. The natural place to start the indetation was column 45, this left me VERY little room to actually get the expression to fit. (Thank goodness for the shorthand form of (||) which made it possible to get the whole thing in.) > ...mark which closing construct goes with which opening construct. Personally, I find that sort of thing very intrusive when reading the source. But then again I'm never going to revert to using illiterate methods again! :-) > ...that's my 2c worth anyway. With the dollar/pound exchange rate at the moment that makes my 1p's worth more valuable than yours. :-)) Regards, Trevor. --------------------------------------------------------------------------- Trevor Jenkins Re: "deemed!" 134 Frankland Rd, Croxley Green, Rickmansworth, WD3 3AU, England email: tfj@apusapus.demon.co.uk radio: G6AJG phone: +44 (0)923 776436 ================================================================================ Archive-Date: Sun, 31 Jan 1993 02:32:13 CST From: adcmail!mtj@uu4.psi.com (Mark Johnson) Reply-To: LitProg@SHSU.edu Message-ID: <9301301827.AA06578@adcmail.atlastele.com> Subject: unsubscribe To: litprog@shsu.edu Date: Sat, 30 Jan 93 10:27:47 PST unsubscribe litprog for mtj@atlastele.com ================================================================================ Archive-Date: Sun, 31 Jan 1993 19:33:16 CST Date: Sun, 31 Jan 1993 19:28:54 -0600 From: gsingh@ho12.eng.ua.edu (Gurbir Singh) Reply-To: LitProg@SHSU.edu Message-ID: <9302010128.AA15422@ho12.eng.ua.edu> To: LitProg@SHSU.edu unsubscribe litprog for gsingh@ho12.eng.ua.edu