Archive-Date: Wed, 01 Dec 1993 08:31:23 CST Sender: LP-Mgr@SHSU.edu From: schrod@iti.informatik.th-darmstadt.de (Joachim Schrod) Reply-To: LitProg@SHSU.edu, schrod@ITI.INFORMATIK.TH-DARMSTADT.DE Subject: Re: Enfin.. Date: 1 Dec 1993 14:05:25 GMT Message-ID: <2di8b6INNjpt@rs18.hrz.th-darmstadt.de> To: LitProg@SHSU.EDU In article <17848173@MVB.SAIC.COM>, D.C.Ince@open.ac.uk (Darrel Ince) writes: > > Second, does anyone know of any books written or in progress that deal with > programming, algorithms and data types that use the literate programming > idea? Knuth's new book about the Stanford Graph Base (basically a preprint of a Vol. 4 part). Joachim -- =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= Joachim Schrod Email: schrod@iti.informatik.th-darmstadt.de Computer Science Department Technical University of Darmstadt, Germany ================================================================================ Archive-Date: Thu, 02 Dec 1993 03:44:02 CST Sender: LP-Mgr@SHSU.edu From: domi@grenoble.hp.com (Dominique Dumont) Reply-To: LitProg@SHSU.edu, domi@GRENOBLE.HP.COM Subject: compiling a tangled file ? Date: 2 Dec 1993 08:25:48 GMT Message-ID: <2dk8qc$nsv@hpscit.sc.hp.com> To: LitProg@SHSU.EDU Hello When I compile a perl script tangled with noweb, I often have syntax errors (well more often than I like to admit :-) ), and the (little) problem I have is that the compiler gives me the line number of the tangled file, not the line number of the web file where the error was actually made. Does anyone have a practical way around this problem ? Do you have the same problem with others webs or compiler ? Thanks ----------------------------------------------------------------------------- Name: Dominique Dumont ^^^^^^ Email: Dominique_Dumont@grenoble.hp.com / O O \ HP Desk: Dominique DUMONT / HP6300/UM ( \____/ ) Address : HEWLETT PACKARD, 38053 Grenoble Cedex 09 FRANCE \______/ Tel,Telnet: (33) 76 62 57 24 - 7 779 5724 Telex,Fax: 980 124 - (33) 76 62 14 88 ----------------------------------------------------------------------------- ================================================================================ Archive-Date: Thu, 02 Dec 1993 06:27:49 CST Sender: LP-Mgr@SHSU.edu Date: Thu, 02 Dec 93 14:20:19 MET From: Zdenek Wagner Reply-To: LitProg@SHSU.edu, WAGNER%CSEARN.BITNET@SHSU.EDU Subject: Re: compiling a tangled file ? To: Literate Progaramming list , domi@GRENOBLE.HP.COM On 2 Dec 1993 08:25:48 GMT said: >Hello > >When I compile a perl script tangled with noweb, I often have syntax errors >(well more often than I like to admit :-) ), and the (little) problem I have >is that the compiler gives me the line number of the tangled file, not the >line number of the web file where the error was actually made. > >Does anyone have a practical way around this problem ? > >Do you have the same problem with others webs or compiler ? > >Thanks > > >----------------------------------------------------------------------------- > Name: Dominique Dumont > ^^^^^^ Email: Dominique_Dumont@grenoble.hp.com > / O O \ HP Desk: Dominique DUMONT / HP6300/UM > ( \____/ ) Address : HEWLETT PACKARD, 38053 Grenoble Cedex 09 FRANCE > \______/ Tel,Telnet: (33) 76 62 57 24 - 7 779 5724 > Telex,Fax: 980 124 - (33) 76 62 14 88 >----------------------------------------------------------------------------- I use CWEB and Borland C++ 3.0. When I have a syntax error, the compiler usually shows the place in the web files. However, there are situations where the error is mistakenly indicated after the end of the tangled file. If this is the case, I change my makefile and invoke a small program which commants out the #line directive. Then the compiler indicates the error in the tangled file and by commented #line directives I manually trace it back to the web source. It's not nice but better than nothing. This kind of trouble is not in various webs but in the compilers :-(. Regards ,~~~/ /` / /| /~~~ / / |_/ /__/ ' | / / /~~/ /~~/ /~~/ /~~/ /\ | /| / /~~/ /~~/ /~~/ /~~/ /~~~ / , / / /~~~ / / /~~~ / \ |/ |/ / /_/ / / / /~~~ / ~~~~ ~~~ ~~~ ' ' ~~~ ' ` ' ' ~~~ ~~/ ' ' ~~~ ' Zdenek Wagner______/ Some gateway between me and you may garble backslash. It will appear on your screen as ã due to problems with EBCDIC <--> ASCII conversion. It has already been corrected on SOME gateways. The address is obsolete and will soon cease to exist! Valid addresses are: ^^ ================================================================================ Archive-Date: Thu, 02 Dec 1993 09:39:59 CST Sender: LP-Mgr@SHSU.edu Date: Thu, 2 Dec 93 10:35:54 EST From: Lee Wittenberg Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET To: LitProg@shsu.edu, domi@grenoble.hp.com Subject: Re: compiling a tangled file ? Message-ID: Dominique Dumont writes: > When I compile a perl script tangled with noweb, I often have syntax errors > (well more often than I like to admit :-) ), and the (little) problem I have > is that the compiler gives me the line number of the tangled file, not the > line number of the web file where the error was actually made. > > Does anyone have a practical way around this problem ? > > Do you have the same problem with others webs or compiler ? noweb provides a facility to insert #line-like directives in the tangled code (I'm not sure what the option is, but it should be easy to find on the notangle manual page). This works beautifully, for C & C++, but I don't know if perl supports any such directive. An alternative (one I frequently use in PAL webs) is to use this option to insert the appropriate line numbers as comments in the tangled code. Then you can find the line in the tangled version and back up to the closest line number comment to find the line in the original web. It's not perfect, but it's better than nothing. Maybe we LP'ers should start insisting that all new programming languages have a #line-like facility, and that all old languages should be retrofitted with one! Or am I just cranky this morning? :-) -- Lee leew@pilot.njin.net ================================================================================ Archive-Date: Fri, 03 Dec 1993 03:23:01 CST Sender: LP-Mgr@SHSU.edu From: domi@grenoble.hp.com (Dominique Dumont) Reply-To: LitProg@SHSU.edu, domi@GRENOBLE.HP.COM Subject: Re: compiling a tangled file ? Date: 3 Dec 1993 08:43:50 GMT Message-ID: <2dmu86$edm@hpscit.sc.hp.com> To: LitProg@SHSU.EDU Thanks for your responses. As usual I think I'll have to hack something. Like a Perl script to help me compile perl scripts (May be I'm heading in a recursive loop :-( ). ----------------------------------------------------------------------------- Name: Dominique Dumont ^^^^^^ Email: Dominique_Dumont@grenoble.hp.com / O O \ HP Desk: Dominique DUMONT / HP6300/UM ( \____/ ) Address : HEWLETT PACKARD, 38053 Grenoble Cedex 09 FRANCE \______/ Tel,Telnet: (33) 76 62 57 24 - 7 779 5724 Telex,Fax: 980 124 - (33) 76 62 14 88 ----------------------------------------------------------------------------- ================================================================================ Archive-Date: Fri, 03 Dec 1993 07:32:34 CST Sender: LP-Mgr@SHSU.edu Date: Fri, 03 Dec 93 15:12:17 MET From: Zdenek Wagner Reply-To: LitProg@SHSU.edu, WAGNER%CSEARN.BITNET@SHSU.EDU Subject: Re: compiling a tangled file ? To: Literate Progaramming list , domi@GRENOBLE.HP.COM On 3 Dec 1993 08:43:50 GMT said: >Thanks for your responses. > >As usual I think I'll have to hack something. Like a Perl script to help me >compile perl scripts (May be I'm heading in a recursive loop :-( ). > > >----------------------------------------------------------------------------- > Name: Dominique Dumont > ^^^^^^ Email: Dominique_Dumont@grenoble.hp.com > / O O \ HP Desk: Dominique DUMONT / HP6300/UM > ( \____/ ) Address : HEWLETT PACKARD, 38053 Grenoble Cedex 09 FRANCE > \______/ Tel,Telnet: (33) 76 62 57 24 - 7 779 5724 > Telex,Fax: 980 124 - (33) 76 62 14 88 >----------------------------------------------------------------------------- The recursion may be surprisingly short. I have a small C++ program which helps me to translate tangled C++ programs produced by CWEB. It's small and easy and it works (I wrote it within a few minutes in raw C++). ,~~~/ /` / /| /~~~ / / |_/ /__/ ' | / / /~~/ /~~/ /~~/ /~~/ /\ | /| / /~~/ /~~/ /~~/ /~~/ /~~~ / , / / /~~~ / / /~~~ / \ |/ |/ / /_/ / / / /~~~ / ~~~~ ~~~ ~~~ ' ' ~~~ ' ` ' ' ~~~ ~~/ ' ' ~~~ ' Zdenek Wagner______/ Some gateway between me and you may garble backslash. It will appear on your screen as ã due to problems with EBCDIC <--> ASCII conversion. It has already been corrected on SOME gateways. The address is obsolete and will soon cease to exist! Valid addresses are: ^^ ================================================================================ Archive-Date: Fri, 03 Dec 1993 13:20:23 CST Sender: LP-Mgr@SHSU.edu Date: 03 Dec 93 14:16:25 EST From: Reply-To: LitProg@SHSU.edu, PJENSEN@CSI.COMPUSERVE.COM To: Subject: CWEB thoughts Message-ID: I just got _The Stanford GraphBase_, and I'm terrifically impressed, as with everything else DEK has written. Some thoughts on CWEB, and one or two questions for anyone who has looked at the sources (I don't have the time right now). I have considerable distaste for C. Among the things I wish had been done differently are: the meaning of = and ==; declaration and typename syntax; open-ended control constructs (vs. Modula's if...end, while...end etc.); use of int for Boolean; line-oriented preprocessor; absence of |var| parameters; treatment of arrays as pointers... But as I read The SGB, I'm thinking - this is okay, I can live happily with this. Just as I believe that LP is far more significant than OO, I also believe it is more important than details of language syntax. (Semantics are different - I still want RAISE, TRY..EXCEPT, TRY..FINALLY, and LOCK..DO.) I'm also using CWEB, and am evolving some guidelines: - Use a semicolon after every fragment reference occurring in a statement-like context; - Enclose the body of every statement-like fragment in {...} except when it looks silly, as for things like "case N: stmts"; - Always use {...} after an |if| which is followed by an |else| (and never put an |if| and a matching |else| in different fragments!); - Otherwise, don't use {...} with control constructs which govern a single statement or single fragment reference, EXCEPT - Do use {...} if the enclosed fragment has multiple defining occurrences (usually things like @ and @.) [ Disclaimer - all this, like indentation, has elements of religious preference - I just post these guidelines for general interest. ] A couple questions, if anyone knows, vis-a-vis CTANGLE: Knuth gets |struct foobar| with both words in boldface, but I get the tag in italic---why? Knuth seems to get no line break between { and a declaration, but I do---why? Thanks and happy LitProgging. Phil Jensen : pjensen@csi.compuserve.com ================================================================================ Archive-Date: Sun, 05 Dec 1993 12:29:51 CST Sender: LP-Mgr@SHSU.edu Date: Sun, 5 Dec 93 13:29:36 EST From: Lee Wittenberg Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET To: LitProg@shsu.edu, PJENSEN@csi.compuserve.com Subject: Re: CWEB thoughts Message-ID: Phil Jensen writes: > I just got _The Stanford GraphBase_, and I'm terrifically impressed, as with > everything else DEK has written. Some thoughts on CWEB, and one or two > questions for anyone who has looked at the sources (I don't have the time > right now). > > [text omitted] > > I'm also using CWEB, and am evolving some guidelines: > - Use a semicolon after every fragment reference occurring in a > statement-like context; > - Enclose the body of every statement-like fragment in {...} except > when it looks silly, as for things like "case N: stmts"; >***- Always use {...} after an |if| which is followed by an |else| (and > never put an |if| and a matching |else| in different fragments!); > - Otherwise, don't use {...} with control constructs which govern a single > statement or single fragment reference, EXCEPT > - Do use {...} if the enclosed fragment has multiple defining occurrences > (usually things like @ and @.) I pretty much agree with all of these, and follow them in my own programs. I would go further with the one I've marked ***, though. I always make sure that each control construct is in a single fragment (with possible sub-fragments, of course, for nested statements). The only exception is in case-like statements: the "case N:" labels and their corresponding statements are almost always in the sub-fragments. > A couple questions, if anyone knows, vis-a-vis CTANGLE: > > Knuth gets |struct foobar| with both words in boldface, but I get the > tag in italic---why? Either the definition of `struct foobar' is in a C chunk that occurs earlier in the web than the text containing `|struct foobar|, or Knuth has snuck an `@s foobar int' into the web somewhere (`@s' is a silent `@f'). > Knuth seems to get no line break between { and a declaration, > but I do---why? He probably puts an `@+' (or a bizarre @t sequence) into the web immediately after the {. -- Lee leew@pilot.njin.net ================================================================================ Archive-Date: Sun, 05 Dec 1993 13:40:38 CST Sender: LP-Mgr@SHSU.edu Message-ID: <199312051940.OAA11152@flaubert.bellcore.com> To: LitProg@SHSU.edu, leew@pilot.njin.net CC: PJENSEN@csi.compuserve.com Subject: Re: CWEB thoughts Date: Sun, 05 Dec 1993 14:40:14 -0500 From: Norman Ramsey Reply-To: LitProg@SHSU.edu, norman@BELLCORE.COM > > A couple questions, if anyone knows, vis-a-vis CTANGLE: > > > > Knuth gets |struct foobar| with both words in boldface, but I get the > > tag in italic---why? > > Either the definition of `struct foobar' is in a C chunk that occurs earlier > in the web than the text containing `|struct foobar|, or Knuth has > snuck an `@s foobar int' into the web somewhere (`@s' is a silent `@f'). > > > Knuth seems to get no line break between { and a declaration, > > but I do---why? > > He probably puts an `@+' (or a bizarre @t sequence) into the web > immediately after the {. And people wonder why I dislike prettyprinting :-) :-) :-) :-) Norman ================================================================================ Archive-Date: Mon, 06 Dec 1993 02:51:57 CST Sender: LP-Mgr@SHSU.edu Date: Mon, 06 Dec 93 10:44:14 MET From: Zdenek Wagner Reply-To: LitProg@SHSU.edu, WAGNER%CSEARN.BITNET@SHSU.EDU Subject: Re: CWEB thoughts To: Literate Progaramming list , norman@BELLCORE.COM On Sun, 05 Dec 1993 14:40:14 -0500 Norman Ramsey said: >> > A couple questions, if anyone knows, vis-a-vis CTANGLE: >> > >> > Knuth gets |struct foobar| with both words in boldface, but I get the >> > tag in italic---why? >> >> Either the definition of `struct foobar' is in a C chunk that occurs earlier >> in the web than the text containing `|struct foobar|, or Knuth has >> snuck an `@s foobar int' into the web somewhere (`@s' is a silent `@f'). >> >> > Knuth seems to get no line break between { and a declaration, >> > but I do---why? >> >> He probably puts an `@+' (or a bizarre @t sequence) into the web >> immediately after the {. > >And people wonder why I dislike prettyprinting :-) :-) :-) :-) > >Norman I still insist on prettyprinting. If I look at my program a year later, I know that the boldface objects are either C++ keywords or my classes/structures. Since |foo| is not a C++ keyword, it defined somewhere as class/structure. Thus I can see more things at the first glance :-) ,~~~/ /` / /| /~~~ / / |_/ /__/ ' | / / /~~/ /~~/ /~~/ /~~/ /\ | /| / /~~/ /~~/ /~~/ /~~/ /~~~ / , / / /~~~ / / /~~~ / \ |/ |/ / /_/ / / / /~~~ / ~~~~ ~~~ ~~~ ' ' ~~~ ' ` ' ' ~~~ ~~/ ' ' ~~~ ' Zdenek Wagner______/ Some gateway between me and you may garble backslash. It will appear on your screen as ã due to problems with EBCDIC <--> ASCII conversion. It has already been corrected on SOME gateways. The address is obsolete and will soon cease to exist! Valid addresses are: ^^ ================================================================================ Archive-Date: Mon, 06 Dec 1993 06:36:01 CST Sender: LP-Mgr@SHSU.edu From: greyham@research.canon.oz.au (Graham Stoney) Reply-To: LitProg@SHSU.edu, greyham@RESEARCH.CANON.OZ.AU Subject: Announcing the c2man mailing list. Message-ID: Keywords: c2man, documentation generator Date: Mon, 6 Dec 1993 06:05:21 GMT To: LitProg@SHSU.EDU For anyone that is not familiar with it, c2man is an automatic documentation tool that extracts comments from C source code to generate functional interface documentation in the same format as sections 2 & 3 of the Unix Programmer's Manual. It requires minimal effort from the programmer by looking for comments in the usual places near the objects they document, rather than imposing a rigid function-comment syntax or requiring that the programmer learn and use a typesetting language. Acceptable documentation can often be generated from existing code with no modifications. There is now a mailing list specifically for c2man users. Topics for discussion could range from anything from where exactly Mullumbimby is, to why looking at Web input files tends to evoke spontaneous convulsions in the user[1]. This is the preferred place to ask questions about the program and discuss modifications and additions with the author and other users. Any existing users or other interested people are encouraged to join by sending mail with no Subject: line to containing: SUBSCRIBE c2man Your name Where `Your name' should be replaced with your real name. C2man itself is available from: how to get: ftp usenet/comp.sources.reviewed/volume03/c2man* from ftp.wustl.edu Europe: ftp /pub/archive/comp.sources/reviewed/c2man* from ftp.informatik.uni-stuttgart.de Patches: ftp pub/netnews/sources.bugs/volume93/sep/c2man* from lth.se Regards, Graham Footnote: 1. Actually, that's probably better kept for comp.programming.literate. -- Graham Stoney, Hardware/Software Engineer Canon Information Systems Research Australia Ph: + 61 2 805 2909 Fax: + 61 2 805 2929 ================================================================================ Archive-Date: Mon, 06 Dec 1993 12:26:24 CST Sender: LP-Mgr@SHSU.edu From: bart@cs.tamu.edu (Bart Childs) Reply-To: LitProg@SHSU.edu, bart@CS.TAMU.EDU Subject: CWEB thoughts and more Date: 3 Dec 1993 22:02:00 GMT Message-ID: <2dod0o$9bk@TAMUTS.TAMU.EDU> Keywords: CWEB FWEB To: LitProg@SHSU.EDU Phil Jensen posed some CWEB questions after reading some of Knuth's Stanford GraphBase. The answer to one question is that Knuth inserted `@+' in many places to supress a line break. The first question is probably that Knuth inserted a format statement like @f foobar struct which says use the same typesetting formatting for foobar that is used for struct. Phil's guidelines were quite good and remind me of the Strunk and White type rules. Some of the same kinds are imbedded in the FWEB documentation from John Krommes. The sources of GraphBase are available for anonymous ftp from labrea.stanford.edu directory /pub/sgb Krommes FWEB 1.40 has been interesting to test. It has a LaTeX style and a verbatim language. The latter gives formatting similar to NoWEB and NuWEB in that the HLL code is not messed up. HOWEVER, I don't like it. The section numbers disappear and show up as part of the section names = I am stating my strong preference for the section numbers appearing at the beginning of the section. If a variable is referenced in the documentation part, you have to find a code part to be able to find the bounds of the section. This is particularly troublesome if you have sections that are documentation only. Still, I am grateful for the contributions of John, Norman Ramsey, Preston Briggs, ... Bart Childs ================================================================================ Archive-Date: Mon, 06 Dec 1993 12:47:42 CST Sender: LP-Mgr@SHSU.edu Date: Mon, 06 Dec 1993 12:46:27 CST From: "George D. Greenwade" Reply-To: LitProg@SHSU.edu, bed_gdg@SHSU.EDU To: info-tex@SHSU.edu, pol-econ@SHSU.edu, ctan@SHSU.edu, TUGBD-L%IRLEARN.BITNET@HEARN.nic.SURFnet.nl, VMSGopher-L@trln.lib.unc.edu, tex-cd@SHSU.edu, litprog@SHSU.edu CC: bparks@wuecona.wustl.edu, bgoffe@whale.st.usm.edu Message-ID: <009769BE.61462A00.19927@SHSU.edu> Subject: Your patience, please........ My apologies for the wide broadcast of this note to a few lists where I have a "presence" (i.e., I manage or co-manage them, have something to do with their archives, etc.). If you have sent me any e-mail within the past week or so and have not heard back, or have attempted to unsubscribe from a list and are awaiting manual removal for some reason, or have noticed that manual maintenance aspects of our archives haven't taken place, or have sent me a personal note and think I'm ignoring you, please bear with me. I will make every effort to get to your post as soon as possible. I intend to get to the unsubs first, any problems on the lists second, any problems with the archives third, then personal items (based on subject lines, anyway). Given that I have to focus at least a modicum of attention to finals this week and next, it may take me a brief time to get caught up with the 1,200 or so messages already awaiting me. If you have a message for me which is truly urgent, please include the word "urgent" in your subject line and I will get to it as soon as I see it before plowing through all the rest. Last week I managed to get myself hospitalized for an impacted lower intestinal tract (so those of you who thought I was full of sh*t were obviously right 8-)). You don't even want to hear what was like nor what done to me -- suffice it to say that it was less than pleasant in both instances, and that recuperation hasn't been all that much joy either. However, I will get better and I will get caught up (not necessarily in that order). Regards and thanks in advance for your patience, 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: Tue, 07 Dec 1993 18:54:46 CST Sender: LP-Mgr@SHSU.edu From: c21vc@kocrsv01.delcoelect.com (Venkataraman Chandrasekhar) Reply-To: LitProg@SHSU.edu, c21vc@KOCRSV01.DELCOELECT.COM Subject: command names Message-ID: <1993Dec7.214400.14556@kocrsv01.delcoelect.com> Date: Tue, 7 Dec 1993 21:44:00 GMT To: LitProg@SHSU.EDU What is written here does not have anything directly to do with literate programming. However, people interested in literate programming may have good insight on the subject and hence I am posting here. In one of our systems, we have a menu of commands. The system has been in use for about a year. The name of one of the commands is misleading. In other words, from its name, I anticipate it to do something somewhat different than what it actually does. There is on-line help and other documentation. A couple of us here are debating the pros and cons of changing the name. We seem to get into this kind of debate periodically. For one of us, the perturbation caused by changing the name is the bigger evil compared to leaving the somewhat imprecise name alone; his point is that users can (and after a while certainly will) learn to work with the imprecise name. These kind of changes add trivial value (they don't add functionality). For theother, changing the name is well worth it; the point is, why should every user fall into this little trap and learn only after necessarily making mistakes ? Also, these kind of changes do add more than trivial value (even though they do not add functionality). A related argument: are more descriptive command names better or briefer ones better ? Even with several words in the command name, there is still some imprecision - does it mean the thing to do is to give up the battle and go for a brief one word tag for each command ? With briefer command names, (for most systems), the entire menu can be fitted on to one screen. However, users have to 'live with' brief command names, for the entire life of the system. Shaker ================================================================================ Archive-Date: Tue, 07 Dec 1993 19:41:23 CST Sender: LP-Mgr@SHSU.edu Date: Tue, 7 Dec 93 20:41:53 -0500 From: koopman@sgi84.ctc.com (Michael G. Koopman) Message-ID: <9312080141.AA20741@sgi84.ctc.com> To: LitProg@SHSU.edu, c21vc@KOCRSV01.DELCOELECT.COM CC: LitProg@SHSU.EDU Subject: command names Reply-To: LitProg@SHSU.edu, koopman@ctc.com Shaker wrote: >What is written here does not have anything directly to do with literate >programming. However, people interested in literate programming may have >good insight on the subject and hence I am posting here. I disagree, the labeling of menus is a part of the literate aspects of a program, IMHO. The label should be based on the logical principles applied globally within a web and should therefore be changed. I expect that a forewarned user should readily accommodate such a logical name change and, as you asserted, new users should learn the menu system quicker and with greater comprehension. >A related argument: are more descriptive command names better or briefer ones >better ? This has the making of a religious war of great proportions. I see it as akin to questioning the utility of scrap psuedonyms within a web. A program which provides both curt and verbose menu descriptions, at the user's discretion, may be the best choice. Michael Koopman (mike) e-mail: koopman@ctc.com Concurrent Technologies Corporation phone: +1-814-269-2637 1450 Scalp Avenue telefax: +1-814-269-2666 Johnstown, PA 15904-3321 USA ICBM: 40-15'N-78-50'W ------------------------------------------------------------- That's all from `Dear Gabby' for this week. ================================================================================ Archive-Date: Wed, 08 Dec 1993 09:52:09 CST Sender: LP-Mgr@SHSU.edu Date: Wed, 8 Dec 93 09:52:46 CST From: thompson@sun1.coe.ttu.edu (Dave Thompson (3/1/93)) Reply-To: LitProg@SHSU.edu, thompson@SUN1.COE.TTU.EDU Message-ID: <9312081552.AA14936@sun1.coe.ttu.edu> To: LitProg@SHSU.edu, c21vc@KOCRSV01.DELCOELECT.COM Subject: Re: command names > A related argument: are more descriptive command names better or briefer ones > better ? Even with several words in the command name, there is still some > imprecision - does it mean the thing to do is to give up the battle and go > for a brief one word tag for each command ? With briefer command names, > (for most systems), the entire menu can be fitted on to one screen. I'm not an expert in human interface design, but have an opinion (and like most noses, it probably smells ;-). The interface should be designed with more than one user type in mind. You need sufficient detail (even if it requires more steps) to guide new users through the software. This might be your multiple screens, or long command names, or what-have-you. You need a second set of commands, probably greatly abbreviated, for your expert users, those who have significant experience with the system (sometimes these are called power users). Even if you use the same displays as for your neophyte users, you should provide "short-cuts" or speed keys. You might allow the user to toggle the menu screens off and work simply with the keyboard (with some help available for infrequently used commands). A third level of user interface might be included in between the first two, for experienced users but not power users. As an example, my text editor is the SemWare Editor. It is a plain text editor that is the descendent of QEdit for PC boxes. It has two user interfaces installed. One is a pull-down menu system (user-configurable) that seems to be the ui of choice these days. It even works with a mouse and is very easy to use. New users (and infrequent editors) can work with the program without learning a lot of keyboard commands. The second user interface is keyboard command driven. It is also user-configurable and I have reprogrammed my keyboard to emulate (mostly) Wordstar. (Now, stop laughing!) Like most of the people who hang around here, I'm a touch typist and hate taking my fingers from the keyboard (hence mice are anathema to me). This user interface works very well for me, and I'm probably a power user of this program. The point is, both user interfaces are necessary to meet the needs of the target audience. Yes, users will learn to use whatever command set you provide. But, the best way is to meet the needs of the user, make things intuitive if possible, and provide multiple ways to achieve the same goal. -=d ======================================================================= David B. Thompson internet: thompson@sun1.coe.ttu.edu Civil Engineering Dept. internet: dthompson@coe2.coe.ttu.edu Texas Tech University internet: wqdbt@ttacs1.ttu.edu P.O. Box 41023 Lubbock, Texas 79409-1023 "Get a haircut and get a *real* job." ======================================================================= ================================================================================ Archive-Date: Thu, 09 Dec 1993 18:40:32 CST Sender: LP-Mgr@SHSU.edu From: krommes@theory.pppl.gov (John Krommes) Subject: Re: CWEB thoughts and more Message-ID: Date: 9 Dec 93 17:31:48 GMT Reply-To: LitProg@SHSU.edu, Krommes@Princeton.EDU To: LitProg@SHSU.EDU Bart Childs writes with regard to FWEB 1.40: > Krommes' FWEB 1.40 has been interesting to test. It has a LaTeX > style and a verbatim language. The latter gives formatting similar > to NoWEB and NuWEB in that the HLL code is not messed up. > HOWEVER, I don't like it. The section numbers disappear and show up > as part of the section names > = > I am stating my strong preference for the section numbers appearing > at the beginning of the section. If a variable is referenced in > the documentation part, you have to find a code part to be able > to find the bounds of the section. This is particularly troublesome > if you have sections that are documentation only. That section numbers do not appear at the beginning of the section in FWEB 1.40 is only a default. It is very simple to make them reappear: just put \numberTeXtrue in the limbo section. For most programming purposes, I agree with Bart; I like the section numbering to be explicit, for precisely the reason he mentions about sections that are documentation only. However, perusing my request queue, for every user who agrees with Bart, there's one who passionately wants the documentation to look more ``book-like.'' FWEB 1.40 (which is still highly experimental) attempts to let the user choose. FWEB 1.40 was announced to the FWEB mailing list but not here because I don't want people, and especially large programming projects, dependent on a stable FWEB to convert just yet. However, I do need patient volunteers to experiment. It's available via anonymous ftp from ftp.pppl.gov:/pub/fweb -- --- John (Mail to krommes@princeton.edu is forwarded to krommes@lyman.pppl.gov == 198.35.4.70. krommes@princeton.edu Ftp files to/from ftp.pppl.gov, NOT princeton.edu (609) 243--2606 or lyman.pppl.gov.) ================================================================================ Archive-Date: Fri, 10 Dec 1993 22:06:53 CST Sender: LP-Mgr@SHSU.edu Message-ID: <9312110402.AA01610@netmail.microsoft.com> From: Eric Landes Reply-To: LitProg@SHSU.edu, ericla@MICROSOFT.COM To: litprog@shsu.edu Date: Fri, 10 Dec 93 14:25:50 TZ Subject: Compiling FWEB 1.40 on Windows NT It's amazingly easy. I did this with Visual C++ 1.0 for NT on an NTFS partition. I also used the 'touch' utility from the Toolbuster CD-ROM. Pretend you are building an ANSI Unix version. Copy defaults.mk and custom.h from \fweb1.40\boot\unix\ansi into \fweb1.40\web. Make the following changes: defaults.mk 1 Change the CC and COMPILER macros from 'gcc' to 'cl'. 2. Change the CFLAGS macro to the options you desire (I used -O2). 3. Change the O macro from 'o' to 'obj'. 4. Change the LDFLAGS and LIBS macros to the options you desire (I didn't use any). 5. Remove the '-o' from the LINK macro. 6. Change the MAKE macro from 'make' to 'nmake'. 7. Change the HWEB macro from 'hweb' to 'hwe'. (optional. Use if you aren't always going to be using NTFS partitions.) makefile 1. Change all '/' to '\'. 2. Uncomment the 'include' directive on line 62 to reflect the Microsoft/Borland format. Comment out the directive on the line above. 3. For the 'touch' command on line 131, change the last two '\' characters back to '/'. (this is for the version of touch I used. Your mileage may vary.) custom.h 1. Change the definition of NULL_FILE_NAME from '/dev/null' to 'NUL' 2. Change the C++ extension on line 89 from 'C++' to 'cpp'. 3. Uncomment the inclusion of malloc.h on line 149. 4. Change the definition of FEWB_INI from '.fweb' to 'fweb.ini'. (optional. I did this for compatibility with the DOS version.) (warning: hack) ftangle.c 1. Around line 3225, MV is defined. Change this definition to refect what you would get if ibmpc was defined. You don't want to define ibmpc for the NT version. After you make these changes, simply type 'nmake bootstrap' and after a couple minutes, you will have FTANGLE.EXE and FWEAVE.EXE. I've got diffs available for these changes if people would like them. If you have any questions/problems, please let me know. I'll be doing this soon for FWEB 1.30a. Eric Landes ericla@microsoft.com ================================================================================ Archive-Date: Sat, 11 Dec 1993 01:39:53 CST Sender: LP-Mgr@SHSU.edu From: thompson@sun1.coe.ttu.edu Subject: comp.programming.literate FAQ Date: 11 Dec 1993 00:00:36 -0500 Message-ID: Reply-To: LitProg@SHSU.edu, thompson@sun1.coe.ttu.edu To: LitProg@SHSU.EDU Archive-name: literate-programming-faq Last-modified: 1993/11/11 Version: 1.0.4 Welcome to the Literate Programming Frequently Asked Questions List ------------------------------------------------------------------- This version was created Thursday - November 11, 1993 and should considered stale after 90 days. Information contained in this document is the best available at preparation. Disclaimer: "This FAQ is presented with no warranties or guarantees of ANY KIND including correctness or fitness for any particular purpose. The author of this document has attempted to verify correctness of the data contained herein; however, slip-ups can and do happen. If you use this data, you do so at your own risk." Copyright 1993 David B. Thompson. All rights reserved worldwide. Permission is granted to copy this document for free distribution so long as it remains intact and unmodified. = ====================================================================== * Introduction: --------------- This document is for new and experienced users of literate programming tools. The purpose is to explain the concept of literate programming and to provide a resource for locating files of interest to literate programmers and those interested in literate programming. The Literate Programming (LitProg) Frequently Asked Questions (FAQ) list is maintained by Dave Thompson, who can be reached at: thompson@sun1.coe.ttu.edu * Preferred mailing address for FAQ related comments/questions. wqdbt@ttacs1.ttu.edu * Forwarded to my pc. Comment and constructive criticism is welcome. Direct flames to /dev/null (or > nul if you're a msdos user! ;-) If you find an error, please report it. I'm particularly interested in establishing the locations of generally available literate programming tools. If you are the author of such a tool and wish to have it included in this list, please send email. Please note this is a work-in-progress. It is *not* complete, and probably will not be complete for some months. Nevertheless, the information contained herein may be useful to some. Use it as it is intended. - ---------------------------------------------------------------------- - Typography: ------------- Major sections of the FAQ are divided by double lines (====). Minor sections and other divisions are separated by single lines (----). Major topics use a "* " as a leader. Minor topics use a "- " as a leader. This should simplify searching for topics. = ====================================================================== Table of Contents: ------------------ * Introduction - Typography. * How to get the FAQ. - Literate Programming FAQ. - FWEB FAQ. * The LitProg newsgroup. * Internet nodes of interest to literate programmers. * What is literate programming? * How do I begin literate programming? * What tools are available and where are they? - c2latex - CLip - CWEB - FunnelWeb - FWEB - noweb - NUWEB - SchemeWEB - Spidery WEB - WinWordWEB * What other resources are available? - Virtual Coursework * Code examples. - Examples included with developer's tools - Cameron Smith's KR-CWEB - Bart Child's examples for FWEB * Bibliographies. * How to anonymously ftp. * Acknowledgements. * End notes. = ====================================================================== * How to get the FAQ: --------------------- - Literate Programming FAQ. --------------------------- You have many ways to get a current copy of this FAQ. One is to use anonymous ftp (if you don't know how, see a later section in this FAQ) to connect to one of the Comprehensive TeX Arvchive Network (CTAN) sites or the Literate Programming Archive and retrieve a copy of the file. (For more information on CTAN and the literate programming archive, see the section below entitled "Internet Nodes of Interest to Literate Programmers.") An alternative is to use the fileserver at SHSU. Send a message to FILESERV@SHSU.EDU (FILESERV@SHSU.BITNET) and include in your message SENDME FAQ.LITPROG The file server will forward a copy of the file to you via email. - ---------------------------------------------------------------------- - FWEB FAQ: ----------- Marcus Speh maintains the FWEB FAQ. The current version number is 1.29. It can be retrieved in the same way as this FAQ; either by anonymous ftp or through the SHSU file server. On the SHSU server, the file name is FAQ.FWEB. Invoke your ftp software, open a connection to NIORD.SHSU.EDU [192.92.115.8], attach to the directory FAQ, and transfer the file FAQ.FWEB. Alternatively, send a message to the file server, FILESERV@SHSU.EDU (FILESERV@SHSU.BITNET), and include the following text in a one line message: SENDME FAQ.FWEB The file server will send the current version of the file via email. The FWEB FAQ exists in various formats, including HyperText (see other resources below). In Europe, the complete distribution can also be obtained from ftp.desy.de [131.169.10.115] in directory /pub/faq/web/fweb/. It is also available from the literate programming archive (LPA) in the directory LPA/documentation/faq/fweb (see the references to LPA below for more information). = ====================================================================== * The LitProg Newsgroup: ------------------------ One of the most important resources is the literate programming newsgroup, comp.programming.literate. You can read this newsgroup using your standard reader. Altenatively, the newsgroup is gated to a mailing list hosted by George Greenwade and Sam Houston State University. You can subscribe by sending mail to the list-server, LISTSERV@SHSU.EDU (or LISTSERV@SHSU.BITNET), and include in the message one line of text: SUBSCRIBE LITPROG "your name in quotes" The list is unmoderated; messages sent to litprog@shsu.edu are automatically distributed to all subscribers and cross-posted to comp.programming.literate. Archives of the mailing list and newsgroup are maintained on niord.shsu.edu [192.92.115.8] in the directory litprog. = ====================================================================== * Internet Nodes of Interest to Literate Programmers: ----------------------------------------------------- The principal nodes of interest to literate programmers are the Literate Programming Archive (LPA hereafter) and the CTAN (Comprehensive TeX Archive Network). The Literate Programming Archive (LPA) is: Node: ftp.th-darmstadt.de [130.83.55.75] Directory: pub/programming/literate-programming Notes: Fastest response during off-U.S. [yep] business hours. The CTAN sites are: ftp host IP CTAN root Institution and Sponsor ------------------------------------------------------------------------- ftp.TeX.ac.UK 134.151.79.32 pub/archive Aston Univ./UK TeX U.G. ftp.Uni-Stuttgart.DE 129.69.8.13 soft/tex Univ. Stuttgart/DANTE e.V ftp.SHSU.edu 192.92.115.10 tex-archive Sam Houston State Univ. Other nodes and directories of interest include: Node: niord.shsu.edu [192.92.115.8] Directory: various (do some snooping!) Notes: Has a gopher server. Node: ftp.desy.de [131.169.10.115] Directory: pub/web. Various documents, samples, and the FWEB FAQ. Notes: Has a www server, http://info.desy.de:80/ = ====================================================================== * What is Literate Programming? ------------------------------- Literate programming is the combination of documentation and source together in a fashion suited for reading by human beings. In fact, literate programs should be enjoyable reading, even inviting! (Sorry Bob, I couldn't resist!) In general, literate programs combine source and documentation in a single file. Literate programming tools then parse the file to produce either readable documentation or compilable source. The WEB style of literate programming was created by D.E. Knuth during the development of his TeX typsetting software. All the original work revolves around a particular literate programming tool called WEB. Knuth says: The philosophy behind WEB is that an experienced system programmer, who wants to provide the best possible documentation of his or her software products, needs two things simultaneously: a language like TeX for formatting, and a language like C for programming. Neither type of language can provide the best documentation by itself; but when both are appropriately combined, we obtain a system that is much more useful than either language separately. The structure of a software program may be thought of as a web that is made up of many interconnected pieces. To document such a program we want to explain each individual part of the web and how it relates to its neighbours. The typographic tools provided by TeX give us an opportunity to explain the local structure of each part by making that structure visible, and the programming tools provided by languages such as C or Fortran make it possible for us to specify the algorithms formally and unambigously. By combining the two, we can develop a style of programming that maximizes our ability to perceive the structure of a complex piece of software, and at the same time the documented programs can be mechanically translated into a working software system that matches the documentation. = ====================================================================== * How to begin literate programming: ------------------------------------ A recommended book is D.E. Knuth's collection of articles (1992) "Literate Programming," Center for the Study of Language and Information, Stanford University, ISBN 0-937073-80-6 (pbk). This book gives insight into Knuth's thoughts as he developed the web system of literate programming (and TeX for typesetting). It does not document methods for literate programming. A recommended book is Wayne Sewell's (1989) "Weaving a Program: Literate Programming in WEB," Van Nostrand Reinhold, ISBN 0-442-31946-0 (pbk). This book focuses on using Knuth's web system. Some talk exists in the newsgroup/mailing list for a Usenet University course in literate programming. I'm sure discussion of this topic will be welcomed. If you are interested, please participate. = ====================================================================== * What Tools are Available: --------------------------- A significant number of tools for literate programming are available. Most have been ported from their original systems, so support multiple computer platforms. If you are the developer of such a tool, and would like to make the software freely available, please send me email and I'll reply with a form (like those below) for you to fill in. (Or short-circuit the process and kludge a form from below. :-) - C2LaTeX: ---------- Developer: John D. Ramsdell System(s) supported: Unix Software supported: Programming language: C. Text formatter: LaTeX but it's easy to change the formatter. Availability: Anonymous ftp from omnigate.clarkson.edu:/pub/tex/tex-programs/c2latex. Readme: Absent. Documentation is in the C source for c2latex. Brief description: C2latex provides simple support for literate programming in C. Given a C source file in which the comments have been written in LaTeX, c2latex converts the C source file into a LaTeX source file. It can be used to produce typeset listings of C programs and/or documentation associated with the program. C2latex produces LaTeX source by implementing a small number of rules. A C comment that starts at the beginning of a line is copied unmodified into the LaTeX source file. Otherwise, non-blank lines are surrounded by a pair of formatting commands (\begin{flushleft} and \end{flushleft}), and the lines are separated by \\*. Each non-blank line is formatted using LaTeX's \verb command, except comments within the line are formatted in an \mbox. Support: Send bug reports to ramsdell@mitre.org. - ---------------------------------------------------------------------- - CLip: ------- Developer: E.W. van Ammers and M.R. Kramer Systems supported: Vax/VMS and MS-DOS. Software supported: An programming language. Plain TeX and LaTeX text formatters. Availability: Anonymous ftp from: CTAN/web/clip LPA/machines/ms-dos LPA/machines/vax sun01.info.wau.nl/CLIP Readme: In distribution. Brief description: Support: Unknown. - ---------------------------------------------------------------------- - CWEB: ------- Developer: Silvio Levy and D.E. Knuth System(s) supported: Unix systems (dos and amiga ports available) Software supported: Languages supported are C and C++. Text formatters are plain TeX and LaTeX. Availability: anonymous ftp from: labrea.stanford.edu/pub/cweb LPA/c.c++ CTAN/web/c_cpp/cweb DOS version in CTAN/web/c_cpp/cwb30p8c DOS version in LPA/machines/ms-dos Amiga version to be posted soon (look at CTAN). Mac port of CTANGLE in LPA/machines/mac LaTeX support in LPA/c.c++ Readme: bundled with above Brief description: Support: bugs to levy@math.berkeley.edu - ---------------------------------------------------------------------- - FunnelWeb: ------------ Developer: Ross N. Williams: ross@guest.adelaide.edu.au Systems supported: MSDOS, Mac, VMS, Sun. Other ports reported. Software supported: For printing, TeX. Otherwise no restrictions. Availability: anonymous ftp from: CTAN/web/funnelweb LPA/independent ftp.adelaide.edu.au/pub/funnelweb Readme: With bundle above. Brief description: FunnelWeb is a production-quality literate-programming tool that emphasises simplicity and reliability. Everything about FunnelWeb, from the simplicity of its language to the comprehensive tutorial in the user's manual, has been designed to make this as simple, as practical, and as usable a tool as possible. Features: + Provides a simple macro preprocessor facility. + Can produce typeset documentation. + Runs on Sun, VMS VAX, Macintosh, PC, and others. + Portable C source code distributed under GNU licence. + Comprehensive user's manual including tutorial. + Programming-language independent. + Can generate multiple output files. + Allows complete control over the output text. + Regression test suite with over 200 tests. + Fully worked example (in /pub/funnelweb/examples). - Requires TeX to produce typeset documentation. - Typesets program code using TT font only. Support: No formal support available. Mailing list maintained with about 50 subscribers. Informal assistance available from mailing list. - ---------------------------------------------------------------------- - FWEB: ------- Developer: John A. Krommes System(s) supported: Unix and DOS platforms Software supported: C, C++, Fortran-77, Fortran-90, Ratfor, TeX, and LaTeX. Text formatters are plain TeX and LaTeX. Availability: anonymous ftp from: lyman.pppl.gov/pub/fweb CTAN/web/fweb LPA/fweb DOS version in LPA/machines/ms-dos Readme: In bundle with above. Brief description: It also has a well-developed user's manual and its own FAQ (see above). It runs on most platforms: VMS, PC, UNIX, and pretty much anything that the GNU C compiler (GCC) is supported for. Support: bug reports to krommes@princeton.edu - ---------------------------------------------------------------------- - noweb: -------- Developer: Norman Ramsey System(s) supported: Unix and DOS platforms Software supported: All programming languages, plain TeX and LaTeX formatters. Availability: anonymous ftp from: csservices.princeton.edu/pub/noweb.shar.Z bellcore.com/pub/norman/noweb.shar.Z CTAN/web/independent/noweb LPA/independent Readme: with bundle above Brief description: noweb is designed to meet the needs of literate programmers while remaining as simple as possible. Its primary advantages are simplicity, extensibility, and language-independence. noweb uses 5 control sequences to WEB's 27. noweb now supports indexing and identifier cross-reference. The simple noweb manual is only 2 pages; documenting the full power of noweave and notangle requires another 3 pages. noweb works ``out of the box'' with any programming language, and its formatter-dependent part is a 60-line nawk program. The primary sacrifice relative to WEB is the loss of prettyprinting. Support: by email to the author - ---------------------------------------------------------------------- - NUWEB: -------- Developer: Preston Briggs: preston@cs.rice.edu Systems supported: Unix systems; Sparcs, RS/6000s, HPs, and (!) MSDOS. Software supported: It's written in C. It works with any programming language (or combination of programming languages) and uses Latex as its text formatter. Availability: anonymous ftp from: Unix: CTAN/web/nuweb DOS: CTAN/web/nuweb-pc LPA/independent Readme: Send mail to preston@cs.rice.edu Brief description: A single program that takes a web file written in a combination of latex and any programming language(s) and produces a latex file that can be pretty printed and a set of files containing code for compilation/interpretation by the appropriate language processors. Strengths include speed, simplicity, multiple languages, nice indices and cross-references, latex. Doesn't require any special macros or macro files. Drawbacks: latex-dependent, no code pretty printing, harder to make indices than cweb. More good stuff: nice support for make, doesn't reformat source files, so they're easy to debug. Lots of control without too much effort. That is, it doesn't do too much! Future directions... Very little change planned, except perhaps refinements in the indexing software. Support: Hack it yourself or send e-mail to preston@cs.rice.edu - ---------------------------------------------------------------------- - SchemeWEB: ------------ Developer: John D. Ramsdell System(s) supported: Unix and DOS platforms Software supported: Programming language: Any dialect of Lisp. Text formatter: LaTeX. Availability: The Unix version is in the Scheme Repository and it is available via anonymous ftp from: nexus.yorku.ca/pub/scheme/utl LPA/lisp The DOS version is part of the PCS/Geneva Scheme system which is available via anonymous ftp from: cui.unige.ch/pub/pcs. LPA/machines/ms-dos Readme: In bundle with above. Brief description: SchemeWEB is a Unix or DOS filter that translates SchemeWEB source into LaTeX source or Lisp source. Lisp code is formatted in typewriter type font and the comments are passed to LaTeX unchanged. Support: Send bug reports to ramsdell@mitre.org. - ---------------------------------------------------------------------- - Spidery WEB: ------------- Developer: Norman Ramsey System(s) supported: Unix and DOS platforms Software supported: Most Algol-like languages, including C, Ada, Pascal, Awk, and many others. Plain TeX and latex for text formatters. Availability: Anonymous ftp from: CTAN Readme: In distribution. Brief description: A system for building language-dependent WEBs. Spider is frozen; no further development is planned. Support: Bug reports to author. - ---------------------------------------------------------------------- - WinWordWEB: ------------- Developer: Lee Wittenberg Systems supported: Needs Microsoft Word for Windows, v.2.x, and, of course, MS-Windows 3.x. Software supported: Any programming language. Word for Windows 2.x for text formatting and file maintenance. Availability: anonymous ftp from: bart.kean.edu:pub/leew World-Wide Web (WWW) Readme: WORDWEB.DOC in the downloadable package describes the system. Brief description: WinWordWEB is a set of a Word for Windows macros (plus a paragraph style) that provide a crude literate programming environment. The ``look and feel'' of the system is based on Norman Ramsey's noweb, but can easily be modified to suit individual tastes. Support: None. WinWordWEB was written as a prototype to see if a WYSIWYG literate programming system was possible. It is intended as a jumping off point for future work by others. However, the system is surprisingly usable as it stands, and the author is interested in hearing from users (satisfied and unsatisfied). Anyone interested in actively supporting (and improving) the product should contact the author via email. = ====================================================================== * Other resources: ------------------ An untapped resource (by me anyway ;-) is the World Wide Web. Marcus Speh has expended considerable effort in this regard. If you're connected to WWW, then access: http://info.desy.de/user/projects/LitProg.html If you aren't connected to WWW, telnet to info.cern.ch and explore. You can reach Marcus' literate programming pages by typing: go http://info.desy.de/user/projects/LitProg.html Help for people who have only Email and neither WWW nor telnet, can be obtained by Email from LISTSERV@INFO.CERN.CH by sending a message containing the command HELP. Instructions will be returned by email. For literate programming documents, you can try anonymous ftp to ftp.desy.de [131.169.10.115] and attach to directory: /pub/userWWW/projects/Announce Another resource of interest to literate programmers is the info-tex mailing list. If you're using (La)TeX as your typsetting system and have access to internet, then you should investigate this mailing list. Mail list service is available through the SHSU list-server. To subscribe, send a message to LISTSERV@SHSU.EDU (LISTSERV@SHSU.BITNET), and include in the message one line of text: SUBSCRIBE INFO-TEX "your name in quotes" The list is unmoderated; messages sent to info-tex@shsu.edu are automatically distributed to all subscribers and cross-posted to comp.text.tex. Archives of the mailing list and newsgroup are maintained on niord.shsu.edu [192.92.115.8] in the directory info-tex. - ---------------------------------------------------------------------- - Virtual Coursework: --------------------- Marcus Speh plans an introductory course on Literate Programming on the Internet, part of the first semester of "Global Network Academy" [GNA], a non-profit corporation incorporated in the state of Texas, affilated with the Usenet University project. The texts/sample programs for this class will be made available via anonymous FTP. A special room on GNA Virtual Campus will be staffed by a consultant in one to two hour shifts. Students with questions can telnet to the virtual campus and ask questions of the staff there. Tuition: Students should agree to work for Global Network Academy in some capacity. This may include agreeing to serve as a consultant next term, donating computing resources which belong to them, helping with programming, etc. If you are interested in registering for the course either as a student or as a consultant, please contact marcus@x4u.desy.de. You will receive a standard reply message; no further action will be taken until January 94. [Editor's note: Because of workload, Marcus requests that email inquiries be limited to a statement of interest for either a student or consultant position until January 1994.] = ====================================================================== * Code Examples: ---------------- Examples of web programs are included with the FWEB, CWEB, and noweb distributions. Cameron Smith converted the K&R calculator program into a literate program. It can be retrieved by anonymous ftp from: niord.shsu.edu [192.92.115.8] directory kr-cweb-sample as krcwsamp.zip or from LPA/Documentation Ross Williams has released a funnelweb example. You can retrieve this file from node ftp.adelaide.edu.au [129.127.40.3] as /pub/funnelweb/examples/except.* This file should be on CTAN as well. = ====================================================================== * Bibliographies: ----------------- Nelson Beebe has collected an extensive bibliography treating literate programming. His work is available for anonymous ftp from ftp.math.utah.edu [128.110.198.2] in directory /pub/tex/bib as files: litprog.bib litprog.ltx. Although I have not verified this, LPA is an alternate source for these files. Note that they are updated frequently (Nelson says several times each week), so be sure to get a fresh copy before extensive use. Joachim Schrod indicates that these files may be updated daily and can be retrieved via anonymous ftp at LPA/documentation. = ====================================================================== * How to anonymously ftp: ------------------------- Pretty much everything mentioned here is available by anonymous FTP. FAQ lists cross-posted to news.answers and rec.answers can be gotten from rtfm.mit.edu [18.70.0.209], under /pub/usenet/news.answers or under /pub/usenet/more.specific.group.name "anonymous FTP" is just a way for files to be stored where anyone can retrieve them over the Net. For example, to retrieve the latest version of the literate programming FAQ, do the following: > ftp rtfm.mit.edu /* connect to the site; message follows */ > anonymous /* type this when it asks for your name */ > /* type your address as the password */ > cd /pub/usenet /* go to the directory you want to be */ > cd comp.programming.literate /* one level down (no slash). */ > dir /* look at what's there */ > get literate-progamming-faq /* get the file; case-sensitive */ > quit /* stop this mysterious thing */ If your FTP program complains that it doesn't know where the site you want to use is, type the numerical address instead of the sitename: > ftp 18.70.0.209 /* connect with numerical address */ If you don't have ftp access, send e-mail to mail-server@rtfm.mit.edu with the single word "help" in the body of the message. Getting binary files (executables, or any compressed files) is only slightly more difficult. You need to set binary mode inside FTP before you transfer the file. > binary /* set binary transfer mode */ > ascii /* set back to text transfer mode */ FAQs and spoiler lists are generally ascii files; everything else is generally binary files. Some common extensions on binary files in archive sites are: .Z Compressed; extract with uncompress .tar.Z Compressed 'tape archive'; uncompress then untar or tar -xvf .gz or .z Gnu gzip; use gunzip (available from prep.gnu.ai.mit.edu) .sit (Mac) StufIt archive .zip Extract with Zip or Unzip .zoo Yet another archive/compress program .lhe (Amiga) ? .lzh Lha archive program. .arj (PC) Arj archive program. .exe (PC) Sometimes self-extracting archives-just execute them. .uue or .UUE Transfer as text file; use uudecode to convert to binary .hqx (Mac) BinHex format; transfer in text mode Generic help can be found in the FAQs of comp.binaries. for how to transfer, extract, and virus-check binary files. (At rtfm.mit.edu) If you can't FTP from your site, use one of the following ftp-by-mail servers: ftpmail@decwrl.dec.com ftpmail@src.doc.ic.ac.uk ftpmail@cs.uow.edu.au ftpmail@grasp.insa-lyon.fr For complete instructions, send a message reading "help" to the server. If you don't know exactly what you're looking for, or exactly where it is, there are programs and servers that can help you. For more info, send e-mail to mail-server@rtfm.mit.with with the body of the message reading send usenet/news.answers/finding-sources Thanks to Aliza R. Panitz (the "buglady") for this text. I copied it verbatim from her post on faq-maintainers with only minor modifications. = ====================================================================== * Acknowledgements: ------------------- This document would not have happened without the help of many people. Among them are Marcus Speh, George Greenwade, Rob Beezer, Joachim Schrod, Piet van Oostrum, and Ross N. Williams. A special thanks to Aliza R. Panitz for the text describing how to execute an anonymous ftp for files of interest. Any omissions from these acknowledgements should be considered an act of stupidity on my part. Of course, the authors of literate programming tools mentioned above all play a vital role in the vitality of literate programming. Furthermore, participants in the comp.programming.literate newsgroup (and associated mailing list) all contributed in various fashions. Thank all of you. = ====================================================================== * End notes: ------------ This document will be evolving over the next few months. I'm planning on adding entries for additional literate programming tools and will expand the sections on examples as more examples become available. Tools I will include are web (the original pascal version), funnelweb, spiderweb, and cnoweb for starters. Others will be added as I find and document them. Omission of a particular tool should not be considered a snub in any sense--simply an error or oversight on my part. History: First release: Fri 10/15/1993 -- Yep, I finally did it! Thu 10/21/93 -- Minor change to ftp instructions. Fri 10/22/93 -- Minor change to stuttgart ip and fweb.faq version. Made reader-recommended changes, lots of re- organization, and added a few tools. Mon 11/01/93 -- Corrected typo in address. Thu 11/11/93 -- Minor change to www. = End of File ========================================================== ================================================================================ Archive-Date: Sat, 11 Dec 1993 21:53:11 CST Sender: LP-Mgr@SHSU.edu From: dpapp@amisk.cs.ualberta.ca (Denis R. Papp) Subject: Watcom C++ Message-ID: Reply-To: LitProg@SHSU.edu, dpapp@amisk.cs.ualberta.ca Date: Sun, 12 Dec 1993 03:10:41 GMT To: LitProg@SHSU.EDU Does anyone know if you can do anything if DOS4GW 1.9+ dont work on your system? Either it returns me to the prompt or hangs, or gives some weird interrupt error (usually Interrupt 0D something like that) I have been informed that it is probably incompatibility with my motherboard... There must be something that can be done Please email me, as I would otherwise miss your reply Thanks -- Denis Papp dpapp@cs.ualberta.ca dpapp@amisk.cs.ualberta.ca "Oh." -- Albert Einstein ================================================================================ Archive-Date: Sun, 12 Dec 1993 16:24:10 CST Sender: LP-Mgr@SHSU.edu From: ses@tipper.oit.unc.edu (Simon E Spero) Reply-To: LitProg@SHSU.edu, ses@TIPPER.OIT.UNC.EDU Subject: emacs hack for cweb users Date: 9 Dec 1993 15:46:50 GMT Message-ID: <2e7h9a$jnf@bigblue.oit.unc.edu> To: LitProg@SHSU.EDU Here's a little hack to do completion on cweb module names in emacs lisp. I find working with abbreviated module names much more confusing than when the names are given in full. This hack keeps the amount of typing the same Simon -- Hackers Local 42- National Union of Computer Operatives, Chapel Hill section ------------------------------------------------------------------------------ Tar Heel Information Services - Nothing but net! | WAIS/Z39.50 spoken here North Carolina - First in Usenet | DoD #612 | Tel: +1-919-962-9107 ================================================================================ Archive-Date: Tue, 14 Dec 1993 17:33:34 CST Sender: LP-Mgr@SHSU.edu From: cfwas@ux1.cts.eiu.edu (William Slough) Reply-To: LitProg@SHSU.edu, cfwas@UX1.CTS.EIU.EDU Subject: Stanford GraphBase on PC's? Message-ID: <1993Dec14.215302.15344@ux1.cts.eiu.edu> Date: Tue, 14 Dec 1993 21:53:02 GMT To: LitProg@SHSU.EDU Is there anyone in this group who has had direct experience with the Stanford GraphBase on a PC with MS-DOS? I have Knuth's book which describes these programs; there is a clear slant toward Unix systems. I am potentially interested in dabbling with these programs, but would prefer not to "reinvent the wheel" regarding makefiles, compiler switches, etc. I have noticed that there is a CWEB tailored to the PC environment; how about the Stanford GraphBase? Any comments are most welcome. Thanks. +----------------------------------------------------------+ | William Slough e-mail: cfwas@eiu.edu | | Department of Mathematics phone : (217)-581-6275 | | Eastern Illinois University office: Old Main 320 | | Charleston, IL 61920 | +----------------------------------------------------------+ ================================================================================ Archive-Date: Thu, 16 Dec 1993 08:36:54 CST Sender: LP-Mgr@SHSU.edu From: perlman@cis.ohio-state.edu (Gary Perlman) Reply-To: LitProg@SHSU.edu, perlman@CIS.OHIO-STATE.EDU Subject: Re: command names Date: 16 Dec 1993 09:04:22 -0500 Message-ID: <2eppt6INN6oa@moose.cis.ohio-state.edu> To: LitProg@SHSU.EDU In article <1993Dec7.214400.14556@kocrsv01.delcoelect.com> c21vc@kocrsv01.delcoelect.com (Venkataraman Chandrasekhar) writes: >In one of our systems, we have a menu of commands. The system has been in use for >about a year. The name of one of the commands is misleading. In other words, >from its name, I anticipate it to do something somewhat different than >what it actually does. There is on-line help and other documentation. > >A couple of us here are debating the pros and cons of changing the name. It's a tradeoff. See the discussion of Experiment 3 in: %A Gary Perlman %D 1984 %T Natural Artificial Languages: Low Level Processes %P 373-419 %O Reviewed in Computing Reviews, 1984, 529 %X An artificial language is one created for concise and precise communication within a limited domain such as mathematics. A natural artificial language is one that people find easy to learn and use. I discuss low level properties of natural artificial languages, especially those in which names are chosen for concepts, and symbols are chosen for names, a class of artificial languages I call linguistically mediated artificial languages. These properties include choosing mnemonic symbols for names, and suggestive names for concepts, and using both internally and externally consistent syntax. I outline a model of processing linguistically mediated artificial language and present results from experiments in support of the model. The results of the experiments are applied to the design of a user interface to a programming system, demonstrating their practicality along with their theoretical interest. The research shows the trade-offs in designing natural artificial languages: naturalness in a specific domain is gained at the cost of generality for other domains. %J International Journal of Man-Machine Studies %V 20 %K user interfaces, cognitive psychology, human factors, systems development %Y Introduction to Basic Concepts An Example of An Artificial Language Descriptions of Important Terms Properties of Natural Artificial Languages A Model of Artificial Language Processing Experimental Evidence Symbols <==> Names Experiment 1: Symbols ==> Names Experiment 2: Names ==> Symbols General Discussion of Symbol <==> Name Experiments Names <==> Concepts Experiment 3: Names ==> Concepts Practical Applications MENUNIX: A Menu-Based Interface to a Programming System Application 1: Symbols <==> Names Application 2: Names <==> Concepts Conclusions Future Work Applicability of Cognitive Psychology to Design Relation to Learning Mathematics References >A related argument: are more descriptive command names better or briefer ones >better ? Even with several words in the command name, there is still some >imprecision - does it mean the thing to do is to give up the battle and go for a >brief one word tag for each command ? With briefer command names, (for most >systems), the entire menu can be fitted on to one screen. However, users have to >'live with' brief command names, for the entire life of the system. I think research recoomends to start people with long names and then provide well-chosen abbreviations for them (as opposed to letting them each try to devise their own). %T Command Names %S II. User Interface Design %A Phil J. Barnard %A Jonathan Grudin %B Handbook of Human-Computer Interaction %E Martin Helander %D 1988 %N 11 %P 237-255 %C New York, NY %I North-Holland %K DESIGN Dialogue %* (c) Copyright 1988 Elsevier Science Publishing Company %Y Introduction Designing Namesets What Designers Need to Keep in Mind What People Do When They Create Names What Designers Do When They Create Names Experimental Contributions Interpreting Experiments Differing Designs of Command Namesets Used in Research Differing Characteristics of Participants in the Experiments Differing Task Domains of Research Experiments Differing Measures of User Performance Summary Natural Names versus System-Oriented or Arbitrary Names Attributes of Names: Specificity, Frequency and Concreteness Abbreviation Effects of Nameset on Individual Names Effects of Task Structure on the Use of Names Using Research Knowledge in Design: Guidelines, Tools and Models Guidelines Background: Choosing and Structuring a Command Language Naming to Facilitate the Name-Operation Mapping Naming to Anticipate User Variability and Permit Customization Context of Command Name Use: Layout, Prompts, Help Designing the System for User Error Tools and Models Design Problems, Approaches, and Unexplored Topics Acknowledgements References -- Gary Perlman, Computer & Information Science, Ohio State University 228 Bolz Hall, 2036 Neil Avenue, Columbus, OH 43210-1277 USA perlman@cis.ohio-state.edu Voice: +01-614-292-2566 Fax: +01-614-292-2911 ================================================================================ Archive-Date: Thu, 16 Dec 1993 09:13:27 CST Sender: LP-Mgr@SHSU.edu From: M.van.Leeuwen@cwi.nl (Marc van Leeuwen) Reply-To: LitProg@SHSU.edu, M.van.Leeuwen@CWI.NL Subject: Release of another version of CWEB Message-ID: Keywords: CWEB 3.x Date: Thu, 16 Dec 1993 14:35:28 GMT To: LitProg@SHSU.EDU Announcement of CWEB 3.x, a new and modified version of CWEB ============================================================ A new version of CWEB, called version 3.x, has been developed and is now officially being released. It is available by anonymous ftp from ftp.cwi.nl, in the directory pub/cweb. The version was developed from the original CWEB of Levy/Knuth, version 2.1, via an intermediate version called auc-cweb by Frank Jensen of Aalborg University. The following list gives the differences with respect to the original CWEB version; these are minor but useful ones, of which the more significant ones were deemed necessary in order to allow existing moderately large C programs to be gradually adapted to a literate style without requiring major organisational changes. - The programs are fully adapted to ANSI C: they support literate programs in that language and are themselves written in ANSI C. - The CWEB system deals explicitly with #include preprocessor directives, just like #define directives were already handled. There are two important reasons for this: firstly the programmer is given control over the relative order of #include and #define directives in the output of CTANGLE, so that the situation that macro definitions disrupt the reading of (system) header files can be avoided, and secondly it allows CWEAVE to be aware of typedef declarations that are hidden in header files, so that their identifiers can be treated properly. - Typedef declarations are found during the first pass of CWEAVE, along with all other |ilk| assingments. This implies that code containing typedef identifiers will be formatted correctly, whether it precedes the typedef declaration or follows it; this conforms to the WEB philosophy of giving the programmer maximal freedom in ordering the material, and also avoids awkward problems when discussing a typedef declaration in its own commentary (apart from the move to ANSI C, this is the change that required the most significant change of the program sources). - A mechanism is provided to explicitly refer to the number of specific sections from within the commentary text, by means of symbolic labels. - Module names are treated syntactically as statements by default, rather than as expressions (although means are provided to treat them as declarations or as expressions). This is really removing a property that was unjustly retained from (Pascal) WEB, since in C statements and expressions have completely separate places in the syntax, and module names almost never stand for expressions; the practical consequence is that it removes the need of putting an invisible semicolon (@;) after almost every module name (or even worse a real semicolon). - A few (further) control codes have been added for the following purposes: to introduce a new section without risking a page break before it (useful between modules that are closely related but have to be separate because they are CTANGLEd to different places); to use the `|' (bitwise or) operator within `|...|'; and to remove one level of indentation from a line (useful for module names that stand for cases in a switch statement). - Arbitrary 8-bit characters may be used in source files. The programs are completely robust against the use of such characters, but using them in program fragments outside strings and comments causes an error. - Several styles of layout can be selected by command line options. The default style aligns all matching braces vertically (unlike other versions of CWEB) without consuming extra space. - CWEAVE can be told to report irreducible scrap sequences (which cause bad layout) by a command line option, i.e., without changing the source file. - The command line syntax has been changed so that with standard naming conventions only a single file name argument is needed, whether or not a change file is being used. - Breaking of long expressions across lines, if necessary, is done in an intelligent way, favouring a break at operators of lowest priority, except when enclosed in parentheses or square brackets. (This is really only a change of the cwebmac format used by TeX.) - A completely new manual has been written (25 pages) providing a (hopefully) more didactical introduction to literate programming and the use of CWEB; it contains a simple but complete sample program illustrating all basic aspects of CWEB, and also a one-page table of all control codes. Furthermore significant changes have been made to the program sources; although these are of little concern to ordinary users, they should make it easier to maintain the programs or to modify them to handle different but similar tasks (e.g., handle a different programming language); indeed they were intended to make the programs more ``literate''. Although the basic structure of the programs has not been greatly altered, almost every part of the source files has undergone rewriting; many minor errors were removed in this process. Some particularly noteworthy points: - All trivial system dependencies have been removed, so that generally no change file is necessary to compile CWEB itself (this mainly means that the referral to "/dev/null" has been eliminated); the only explicit system dependencies are the assumption of the ASCII character set and the assumed interpretation of the value returned from |main|. - The parser of CWEAVE operates by interpretation of a set of grammar rules that are explicitly stored in a (statically initialised linear) table. The formatting rules are given by easily interpreted format strings. Altogether there is a clean separation between parser and grammar (somewhat along the lines of the SPIDER system), making it relatively easy to alter the set of rules; in fact a system for dynamically selecting rules according to command line arguments is present that could easily be extended to support more variants. - The programs use a header file read in by #include to share common declarations between different compilation units (as is normal practice in multi-file C programs), instead of using the CWEB inclusion facility (@i) for this, which would lead to the text being replicated into all CWEB documents. In doing so, the programs also set a good example of how the multiple output file facility can be effectively used, since the header file is produced by CTANGLE from the same source file (common.w) that contains the definitions of the objects that the declarations in the header file refer to. - The style of the programs has been altered to a more C-like one on numerous points where there were complications that could only be explained by the Pascal origins of the programs. For instance, since the program usually manipulates pointers into arrays rather than the indices of the elements, it is more natural to use NULL to indicate an exceptional value (e.g., the end of a list) than the value of a pointer to a specially reserved element. - In programs and documentation a systematic distinction is made between sections, which are numbered pieces of the CWEB document that may or may not contain a program fragment, and modules, which are named pieces of C code that are defined in one or more sections; thus a source of confusion is removed. As I recently found out, there is now an updated version of the original Levy/Knuth CWEB, called version 3.1. Therefore the version announced here introduces a forking in the development history of CWEB, which is of course regrettable, and which explains the strange version number of this version, that would otherwise have been called CWEB 3.0. Apparently the main change in version 3.1 is the support for C++ and therefore a fortiori for ANSI C; further small changes have been made in direction different from those for version 3.x, such as handling 8-bit characters in identifiers. Since it is my intention to serve the literate programming community, not to divide it, I will make an attempt at some future time to merge the two branches by incorporating those additions if version 3.1 that are still relevant to 3.x, most importantly to extend the support for C++ (currently the support is limited to what was present in version 2.1, which is not likely to be sufficient in view of the evolutionary nature of C++). Meanwhile I deemed it wise not to hold up the release of the current version until such changes have been made. In other respects as well, I plan to provide active support for CWEB 3.x. For one thing, it will be used to convert the computer algebra program LiE, which is moderately large (currently about 600Kb source code in some 65 files), to a literate program; this should provide a good test for the practical usability. Therefore all bug reports, comments and suggested can be sent to the address below. Marc van Leeuwen CWI, Amsterdam, The Netherlands e-mail: M.van.Leeuwen@cwi.nl ================================================================================ Archive-Date: Mon, 20 Dec 1993 03:21:48 CST Sender: LP-Mgr@SHSU.edu Date: Mon, 20 Dec 93 10:19:23 MET From: Zdenek Wagner Reply-To: LitProg@SHSU.edu, WAGNER%CSEARN.BITNET@SHSU.EDU Subject: nuweb for 286 To: Literate Progaramming list Hello, I am partially busy and partially lazy to study nuweb code so I have the following question: did anybody managed to compile nuweb for 286 processor? I just compiled it with my Borland C++ and when trying to run, it reboots the computer. Any help will be appreciated. Merry Christmas ,~~~/ /` / /| /~~~ / / |_/ /__/ ' | / / /~~/ /~~/ /~~/ /~~/ /\ | /| / /~~/ /~~/ /~~/ /~~/ /~~~ / , / / /~~~ / / /~~~ / \ |/ |/ / /_/ / / / /~~~ / ~~~~ ~~~ ~~~ ' ' ~~~ ' ` ' ' ~~~ ~~/ ' ' ~~~ ' Zdenek Wagner______/ Some gateway between me and you may garble backslash. It will appear on your screen as ã due to problems with EBCDIC <--> ASCII conversion. It has already been corrected on SOME gateways. The address is obsolete and will soon cease to exist! Valid addresses are: ^^ ================================================================================ Archive-Date: Mon, 20 Dec 1993 03:58:49 CST Sender: LP-Mgr@SHSU.edu From: Thorbjoern Ravn Andersen Reply-To: LitProg@SHSU.edu, ravn@IMADA.OU.DK Message-ID: <199312200958.AA16768@imada.ou.dk> Subject: Re: nuweb for 286 To: LitProg@SHSU.edu Date: Mon, 20 Dec 1993 10:58:26 +0100 (MET) MIME-Version: 1.0 Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: 8bit Zdenek Wagner | I am partially busy and partially lazy to study nuweb code so I have the | following question: did anybody managed to compile nuweb for 286 processor? | I just compiled it with my Borland C++ and when trying to run, it reboots the | computer. I have nuweb 0.87 running on my 486 system (and I think I compiled it for the 8086 processor), and it works like a charm. I have, however, incorporated my patches for AUC-TeX (plus some Borland Pascal support and Dominique de Waleffes comment patch) so the resulting TeX output requires a relatively new LaTeX (like emTeX) to run. If there is anybody who wants a copy, I will make it available for ftp. (I am not probing into protected mode or anything like it, but if some wizard wants to do it, I can bundle the source with the binary.) Regards, -- Thorbjo/rn Andersen ravn@imada.ou.dk ================================================================================ Archive-Date: Mon, 20 Dec 1993 05:12:10 CST Sender: LP-Mgr@SHSU.edu Date: Mon, 20 Dec 93 12:08:17 +0100 From: ddw2@sunbim.be (Dominique de Waleffe) Reply-To: LitProg@SHSU.edu, ddw2@SUNBIM.BE Message-ID: <9312201108.AA10817@amadeus.sunbim.be> To: LitProg@SHSU.edu, ravn@IMADA.OU.DK Subject: Re: nuweb for 286 References: <199312200947.AA16664@imada.ou.dk> <199312200958.AA16768@imada.ou.dk> Thorbjoern> I have nuweb 0.87 running on my 486 system (and I think I Thorbjoern> compiled it for the 8086 processor), and it works like a Thorbjoern> charm. Thorbjoern> I have, however, incorporated my patches for AUC-TeX Thorbjoern> (plus some Borland Pascal support and Dominique de Thorbjoern> Waleffes comment patch) so the resulting TeX output Thorbjoern> requires a relatively new LaTeX (like emTeX) to run. Thorbjoern> If there is anybody who wants a copy, I will make it Thorbjoern> available for ftp. I've been meaning to integrate your patches and mine into the latest 0.87 but haven't got any time to do it in months. I'd appreciate being able to get a patched copy of 0.87... SO if you could put it up for ftp... If you don't for any reason, could you send me the patched nuweb? Or a diff, that will do. Dominique =============================================== Merry Christmas and a Happy and Successful 1994 /\ * / \ * * * /o/\ \ Dominique de Waleffe ddw@sunbim.be * / / o \ * BIM sa / /o \ \ * Chee de Louvain, 510 Tel: +32 2 719 26 14 / o-------o\ B-1930 Zaventem Fax: +32 2 725 47 83 ------o------- * Belgium _______||___________ ______________________ ================================================================================ Archive-Date: Mon, 20 Dec 1993 06:53:26 CST Sender: LP-Mgr@SHSU.edu From: jacojn@inet.uni-c.dk (Jacob Nielsen) Reply-To: LitProg@SHSU.edu, jacojn@INET.UNI-C.DK Subject: Re: nuweb for 286 Date: Mon, 20 Dec 1993 12:23:23 GMT Message-ID: <75639020315698@inet.uni-c.dk> To: LitProg@SHSU.EDU >I am partially busy and partially lazy to study nuweb code so I have the >following question: did anybody managed to compile nuweb for 286 processor? >I just compiled it with my Borland C++ and when trying to run, it reboots the >computer. The only problem I've ever had with nuweb, is the use of 'tempnam' to generate tempoary files. I have never quite got it working, but then I work on UN*X :-), so I can allways think of some long file name, that I'm quite sure wont colide with other file names. You could consider altering the call of 'tempnam' - it's easy to find - to produce something like tmmssxx.tmp, where 'mm' is minuts, 'ss' is seconds and xx is the number of the processed file. Asuming you don't have files named like that, all will work as a charm. PS: nuweb removes its temporary files after use. Merry christmas, Jacob -- Jacob Nielsen Email: jacojn@inet.uni-c.dk (my private account) or bc898574@bbar.dth.dk (my account at the university) ================================================================================ Archive-Date: Mon, 20 Dec 1993 08:12:47 CST Sender: LP-Mgr@SHSU.edu To: litprog@shsu.edu Date: Mon, 20 Dec 1993 13:06:14 GMT From: proj49@imsor.dth.dk (Jacob Mohr Nielsen (ogm - 2/94)) Reply-To: LitProg@SHSU.edu, proj49@IMSOR.DTH.DK Message-ID: References: <2esmqj$qr1@canopus.cc.umanitoba.ca>, <1993Dec19.222735.19369@labtam.labtam.oz.au> Subject: Re: Movies on the big screen The Killing Fields ================================================================================ Archive-Date: Mon, 20 Dec 1993 14:30:02 CST Sender: LP-Mgr@SHSU.edu Message-ID: <9312201933.AA07549@sun-8.cae.wisc.edu> Date: Mon, 20 Dec 93 13:33:08 CST From: tomas@cae.wisc.edu Reply-To: LitProg@SHSU.edu, tomas@CAE.WISC.EDU Subject: Re: nuweb for 286 To: LitProg@SHSU.edu, jacojn@INET.UNI-C.DK > The only problem I've ever had with nuweb, is the use of 'tempnam' to > generate tempoary files. I have never quite got it working, but then I > work on UN*X :-), so I can allways think of some long file name, that > I'm quite sure wont colide with other file names. That's odd. I thought |tempnam| _was_ a UNIXism. I hacked |tempnam| to the ANSI |tmpnam| and then diddled with that to get it to work on my Amigas. (I had to make sure the temporary file went to the same directory as the code so |rename| would work.) > > You could consider altering the call of 'tempnam' - it's easy to find - > to produce something like tmmssxx.tmp, where 'mm' is minuts, 'ss' is seconds > and xx is the number of the processed file. Asuming you don't have files > named like that, all will work as a charm. PS: nuweb removes its temporary > files after use. > > Merry christmas, > > Jacob > -- > Jacob Nielsen > Email: jacojn@inet.uni-c.dk (my private account) > or bc898574@bbar.dth.dk (my account at the university) > I have found nuweb to be terrifically useful. The ability to make many output files from one web makes it pleasant to write wrapper code to test certain functions one at a time. I was quite pleased with CWEB until I started hacking about with nuweb. Good work Preston! -- Ciao! Tomas Willis (tomas@cae.wisc.edu) @ @ -------------------------------------------------------------------------- | There is a bright side to being the first and only intelligent beings in | | our galaxy - we will have the chance to found the Galactic Empire! | | --- some astronomy student --- | -------------------------------------------------------------------------- ================================================================================ Archive-Date: Mon, 20 Dec 1993 15:05:16 CST Sender: LP-Mgr@SHSU.edu Date: Mon, 20 Dec 1993 13:59:28 03d-7 ((null)) From: "Michael J. Carter" Reply-To: LitProg@SHSU.edu, carter@SSTCX1.LANL.GOV Subject: To: LitProg@SHSU.edu Message-ID: MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=us-ascii subscribe *-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-* | Michael J. Carter Internet: mcarter@lanl.gov | * Space & Atmospheric Sciences Phone: (505)665-6529 * | Los Alamos National Laboratory Fax: (505)665-7395 | *-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-* ================================================================================ Archive-Date: Mon, 20 Dec 1993 18:31:14 CST Sender: LP-Mgr@SHSU.edu From: pgjtasse@atlas.cs.upei.ca (Judy Tassell) Reply-To: LitProg@SHSU.edu, pgjtasse@ATLAS.CS.UPEI.CA Subject: An Encryption Decrypter Date: 20 Dec 1993 19:08:22 -0400 Message-ID: <2f5b96$ast@atlas.cs.upei.ca> To: LitProg@SHSU.EDU Hiya. I was wondering if anyone new of a way to derive the algorithm of an encryption meathod with a list of the encoded words and their decoded values. I red in a book, _The Fools Run_ (fiction), that someone had developed a program to do something liek this, and I was wondering if their were any in existance. Preferably written in (Turbo) Pascal, (Turbo) C(+,++), or IBM (Turbo) Assembly. Any input would be appretiated. -Charles Tassell ================================================================================ Archive-Date: Mon, 20 Dec 1993 19:24:29 CST Sender: LP-Mgr@SHSU.edu From: mauer@mcs.anl.gov (Andrew Mauer) Reply-To: LitProg@SHSU.edu, mauer@MCS.ANL.GOV Subject: Using noweb with Underscores Message-ID: Date: Tue, 21 Dec 1993 00:29:10 GMT To: LitProg@SHSU.EDU I would like to use 'noweb', and have written several pieces of code with it. Recently, I decided to convert all of by bastardized nuweb/noweb code to plain noweb, and I came across a rather ugly "feature" of noweb which seems to be the fault of LaTeX (??). I use "indexing" mainly to get numbered chunks. I like to have descriptive file names, and this frequently means *underscores*. I like to call the root node for a file by it's name, so I have a file "Expression_List.h" and I want a scrap <>. Unfortunately, this causes latex (specifically amslatex, but I don't think that matters) to barf when trying to tex... I would not mind enclosing the filename in [[ ... ]] , or preferably the shorthand verb |...|, but this causes the notangle -R method of generating your code to fail badly. It seems to me that the fix should be to allow -RExpression_List.h to extract the node <<[[Expression_List.h]]>>. Let me know what you think. /Andrew/ P.S. Let me know if you want the patches, too. -- /Andrew Mauer/ mauer@mcs.anl.gov ================================================================================ Archive-Date: Mon, 20 Dec 1993 23:45:45 CST Sender: LP-Mgr@SHSU.edu Message-ID: <199312210542.AAA15151@flaubert.bellcore.com> To: LitProg@SHSU.edu, mauer@mcs.anl.gov Subject: Re: Using noweb with Underscores Date: Tue, 21 Dec 1993 00:42:15 -0500 From: Norman Ramsey Reply-To: LitProg@SHSU.edu, norman@BELLCORE.COM > I like to have > descriptive file names, and this frequently means *underscores*. I > like to call the root node for a file by it's name, so I have a file > "Expression_List.h" and I want a scrap <>. > Unfortunately, this causes latex (specifically amslatex, but I don't > think that matters) to barf when trying to tex... > > I would not mind enclosing the filename in [[ ... ]] , or preferably > the shorthand verb |...|, but this causes the notangle -R > method of generating your code to fail badly. Interesting. I tend to avoid underscores in file names (I prefer a hyphen), so I have never faced this issue. What's wrong with notangle -R'[[Expression_List.h]]' ? Do you just find it ugly or am I missing some deeper issue? There are various other games you could play. If you're not using much math, you might find something like \catcode`\_=13 profitable; this would eliminate _ as a special character. That's probably what I would do. (I might be wrong about 13; you should check the TeXbook for the catcode of `other'). > It seems to me that the fix should be to allow -RExpression_List.h to > extract the node <<[[Expression_List.h]]>>. I'm unenthusiastic about this idea, but the world won't end if you do it. Norman ================================================================================ Archive-Date: Tue, 21 Dec 1993 01:06:46 CST Sender: LP-Mgr@SHSU.edu From: Klaus Guntermann Reply-To: LitProg@SHSU.edu, gunterma@ITI.INFORMATIK.TH-DARMSTADT.DE Message-ID: <9312210705.AA16243@sphinx.iti.informatik.th-darmstadt.de> Subject: cweave 3.1 optimization To: LitProg@shsu.edu Date: Tue, 21 Dec 1993 08:05:40 +0100 (MEZ) Content-Type: text Dear cweb users, since the Stanford GraphBase was published we had an increasing need to use cweb to create formatted and printed program listings. But doing so I ran into an incredible time penalty for using cweave. After some investigation I found out, that problems with the NFS implementation on our workstations were heavily exercised by cweave in the second phase. The reason is that in section 78 (definition of |flush_buffer|) the macro |c_line_write| contains a call to |fflush|. This seems to be absolutely unnecessary. At least I cannot see why the file buffers should be flushed here. When I removed this call the timings for cweave in phase 2 improved dramatically for us. But also for other machines I noticed a considerable speed up in system time for larger cweave jobs (eg. cweaving cweave) without the |fflush|. Thus I would recommend to remove this. To make sure that not any negative effects are introduced by this - although I cannot imagine how that should happen - I include a change file for this optimization. Before that change is included in one of the next releases, everybody can test it and report problems to me. Silvio Levy is willing to include that change in the next official release, if no problems are reported. I would also like to hear of any dramatic improvements (by mail, please). To make sure that we did not introduce our NFS performance problem by choosing bad parameters, I would like to hear in detail about the behaviour of this change in different releases of AIX 3 on IBM RS/6000s (we are on 3.2.4). Thank you in advance. Including seasonal greetings from Darmstadt, Klaus Guntermann TH Darmstadt (Technical University) FB Informatik (Computer Science Department) Alexanderstr. 10, D-64283 Darmstadt, FR Germany 8<------------------------------------------------------------cweave.ch There are some performance penalties when using fflush too heavily, mainly when the file system is accessed via NFS. As there is no need to flush the file buffers so often, we can omit that from cweave. Klaus Guntermann ----- First update all parts which refer to version numbering, and add a trailing tag. @x % Version 3.1 --- November 1993 @y % Version 3.1 --- November 1993 % Update 3.1-1 --- remove fflush on files, December 1993 % by Klaus Guntermann @z @x \def\title{CWEAVE (Version 3.1)} \def\topofcontents{\null\vfill \centerline{\titlefont The {\ttitlefont CWEAVE} processor} \vskip 15pt \centerline{(Version 3.1)} \vfill} @y \def\title{CWEAVE (Version 3.1-1)} \def\topofcontents{\null\vfill \centerline{\titlefont The {\ttitlefont CWEAVE} processor} \vskip 15pt \centerline{(Version 3.1-1)} \vfill} @z @x @d banner "This is CWEAVE (Version 3.1)\n" @y @d banner "This is CWEAVE (Version 3.1-1)\n" @z ----- And here the real change takes place. Do not 'fflush(active_file)' @x @d c_line_write(c) fflush(active_file),fwrite(out_buf+1,sizeof(char),c,active_file) @y @d c_line_write(c) fwrite(out_buf+1,sizeof(char),c,active_file) @z 8<------------------------------------------------------------ ================================================================================ Archive-Date: Tue, 21 Dec 1993 11:15:44 CST Sender: LP-Mgr@SHSU.edu From: Andrew Mauer Reply-To: LitProg@SHSU.edu, mauer@MCS.ANL.GOV Date: Tue, 21 Dec 93 09:44:36 CST Message-ID: <9312211544.AA08460@canopus.mcs.anl.gov> To: Norman Ramsey CC: LitProg@shsu.edu Subject: Re: Using noweb with Underscores References: <199312210542.AAA15151@flaubert.bellcore.com> Andrew Mauer said > I like to have > descriptive file names, and this frequently means *underscores*. I > like to call the root node for a file by it's name, so I have a file > "Expression_List.h" and I want a scrap <>. > Unfortunately, this causes latex (specifically amslatex, but I don't > think that matters) to barf when trying to tex... > > I would not mind enclosing the filename in [[ ... ]] , or preferably > the shorthand verb |...|, but this causes the notangle -R > method of generating your code to fail badly. Norman Ramsey said: > Interesting. I tend to avoid underscores in file names (I prefer a > hyphen), so I have never faced this issue. What's wrong with > notangle -R'[[Expression_List.h]]' > ? > Do you just find it ugly or am I missing some deeper issue? The problem I have is with automatic extraction a la: %.cc: %.nw $(TANGLE) $(TANGLE_FLAGS) -R$@ $(web-files) > $@ or some variant thereof. This would force me to name EVERY root chunk in the [[filename]] style. This isn't aesthetically pleasing, and it would mean fixing up quite a bit of existing code :-( . > There are various other games you could play. If you're not using > much math, you might find something like > \catcode`\_=13 > profitable; this would eliminate _ as a special character. That's > probably what I would do. (I might be wrong about 13; you should > check the TeXbook for the catcode of `other'). [The catcode for "other" is 12.] There must be some \catcode resetting going on in the support code; I perform this in the text immediately before the problem area: \catcode`\_=\other <>= [...] But when TeX reads the <> line, it still thinks that _ (underscore) is a subscript (catcode 8). (I can't figure out why, and I believe I looked at all the macros that get executed... ?) There is another problem with this. Even if you catcode an underscore to \letter or \other, it does not *print* as an underscore. It comes out as a little raised dot. This is obviously a Tex problem, but I'm not an expert. I would appreciate any TeX expert advice. (There is presumably an easy solution...) /Andrew/ ================================================================================ Archive-Date: Tue, 21 Dec 1993 15:32:26 CST Sender: LP-Mgr@SHSU.edu From: fuellen@athena.mit.edu (Georg Fuellen) Reply-To: LitProg@SHSU.edu, fuellen@ATHENA.MIT.EDU Subject: Re: An Encryption Decrypter Date: 21 Dec 1993 20:27:19 GMT Message-ID: <2f7m77$bgq@senator-bedfellow.MIT.EDU> To: LitProg@SHSU.EDU In article <2f5b96$ast@atlas.cs.upei.ca>, pgjtasse@atlas.cs.upei.ca (Judy Tassell) writes: |> Hiya. I was wondering if anyone new of a way to derive the algorithm of |> an encryption meathod with a list of the encoded words and their decoded |> values. I red in a book, _The Fools Run_ (fiction), that someone had |> developed a program to do something liek this, and I was wondering if their |> were any in existance. Preferably written in (Turbo) Pascal, (Turbo) |> C(+,++), or IBM (Turbo) Assembly. Any input would be appretiated. |> -Charles Tassell In general, there is no way to derive the algorithm, and any known plaintext/ciphertext technique (you are hinting at this) does presumably not enable decryption of new messages EVEN IF THE ALGORITHM IS KNOWN TO BE RSA ENCRYPTION (for instance), but the key is kept secret. There is a nice faq in sci.crypt, to which follow-ups are redirected. Regards, georg fuellen@mit.edu The convex hull of all disclaimers made on usenet last year applies to this mess ================================================================================ Archive-Date: Tue, 21 Dec 1993 17:26:40 CST Sender: LP-Mgr@SHSU.edu From: paul@opal.com.au (Paul Bandler) Reply-To: LitProg@SHSU.edu, paul@OPAL.COM.AU Subject: cweb for C++ API Extractor? - Request for Information Message-ID: <1993Dec21.215543.5072@opal.com.au> Date: Tue, 21 Dec 1993 21:55:43 GMT To: LitProg@SHSU.EDU I am new to reading this group so appologies for what is I'm sure a very basic question. We're at the begining for a C++ development and establishing coding / documentation practises for the project. We would like to be able to build a high quality (i.e. to be distributed as part of a software product) programmer's reference manual derived from the C++ source files. In investigating this I have been lead to this news group and understand that there is a program called cweb which may be of assistance to us. Could someone advise:- 1. Whether cweb is a tool suitable to my purpose? 2. Is cweb available in the public domain at an archive site? If so, where? 3. Would someone be willing to send me an example cweb input and output so that I can get an idea of what is involved? 4. Would it be possible to integrate cweb with Framemaker? 5. There is some resistance here to the effect of needing to instrument ones source code extensively in order to be able to create product quality end-user documentation from it. Can anyone comment as the feasibility/desirability of this approach or indicate whether this has been achieved successfully in practice somewhere? I would appreciate any respondants copying me directly by email in order to ensure timely delivery. Thanks in anticipation, Paul Bandler Project Manager Opal Communications Systems Melbourne, VIC, Australia paul@opal.com.au ================================================================================ Archive-Date: Wed, 22 Dec 1993 05:25:34 CST Sender: LP-Mgr@SHSU.edu From: mwj@cnve.rz.uni-jena.de (Johannes Waldmann) Reply-To: LitProg@SHSU.edu, mwj@CNVE.RZ.UNI-JENA.DE Subject: DEK's `Stanford Graph Base' book existing / available? Date: 22 Dec 1993 11:36:53 +0100 Message-ID: <2f9805$jt6@cnve.rz.uni-jena.de> To: LitProg@SHSU.EDU Some time ago a new book by Knuth `The Stanford Graph Base' was announced in some newsgroup. Is it available, meanwhile? Is it something like his TeX/MF books, or rather like Art Of Computer Programming? (I read it should become Vol 4 of this series.) Johannes - mwj@rz.uni-jena.de ================================================================================ Archive-Date: Wed, 22 Dec 1993 12:11:31 CST Sender: LP-Mgr@SHSU.edu From: schrod@iti.informatik.th-darmstadt.de (Joachim Schrod) Reply-To: LitProg@SHSU.edu, schrod@ITI.INFORMATIK.TH-DARMSTADT.DE Subject: Re: Using noweb with Underscores Date: 22 Dec 1993 17:08:29 GMT Message-ID: <2f9uud$efi@rs18.hrz.th-darmstadt.de> To: LitProg@SHSU.EDU In article <18696317@MVB.SAIC.COM>, Norman Ramsey writes: > > There are various other games you could play. If you're not using > much math, you might find something like > \catcode`\_=13 > profitable; this would eliminate _ as a special character. That's > probably what I would do. (I might be wrong about 13; you should > check the TeXbook for the catcode of `other'). It's 12. In fact, you can use \catcode`\_=\active \def_{\ifmmode \sb \else \_\fi} and get an underscore in text and a subscript in math mode, as long as you don't use _ as the first char in a table entry. (And, of course, as long as you put these lines in a macro file; don't stick them at the head of your document.) (This holds for both LaTeX and plain TeX.) Cheers, Joachim -- =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= Joachim Schrod Email: schrod@iti.informatik.th-darmstadt.de Computer Science Department Technical University of Darmstadt, Germany ================================================================================ Archive-Date: Wed, 22 Dec 1993 12:26:30 CST Sender: LP-Mgr@SHSU.edu From: d.love@dl.ac.uk (Dave Love) Reply-To: LitProg@SHSU.edu, d.love@DL.AC.UK Subject: Re: Using noweb with Underscores Date: 22 Dec 1993 18:00:05 GMT Message-ID: To: LitProg@SHSU.EDU >>>>> "Andrew" == Andrew Mauer writes: Andrew> There must be some \catcode resetting going on in the support code; There is -- the catcodes are not saved and reset from the values they have when the code which sets the scrap is invoked, just flipped to the canonical values. [...] Andrew> There is another problem with this. Even if you catcode an underscore Andrew> to \letter or \other, it does not *print* as an underscore. It comes Andrew> out as a little raised dot. This is obviously a Tex problem, but I'm Andrew> not an expert. I would appreciate any TeX expert advice. (There is Andrew> presumably an easy solution...) The Computer Modern text fonts (for instance) don't contain an underscore. If you want _ to print as underscore I think you want, in general, just: \catcode`\_=\active % so `_' \equiv `\_' If you then want to use subscripts, you have either to use an \everymath to reset the catcode of _ or to use \sb. I support Norman's recommendation of dashes rather than underscores if your OS allows and caution against catcode hacking unless you're prepared for surprises. Some macros written by TeX gurus that expect filenames as arguments will barf on names containing underscores and other special characters anyhow. Incidentally, it is likely that the noweb macros will need some alteration for use with the recently-surfaced LaTeX 2e (the new standard version of LaTeX when it gets out of test). I will attend to this in the new year if no one else does. ================================================================================ Archive-Date: Wed, 22 Dec 1993 13:25:20 CST Sender: LP-Mgr@SHSU.edu From: schrod@iti.informatik.th-darmstadt.de (Joachim Schrod) Reply-To: LitProg@SHSU.edu, schrod@ITI.INFORMATIK.TH-DARMSTADT.DE Subject: Re: nuweb for 286 Date: 22 Dec 1993 17:02:34 GMT Message-ID: <2f9uja$efi@rs18.hrz.th-darmstadt.de> To: LitProg@SHSU.EDU In article <18678804@MVB.SAIC.COM>, tomas@cae.wisc.edu writes: > > The only problem I've ever had with nuweb, is the use of 'tempnam' to > > generate tempoary files. I have never quite got it working, but then I > > work on UN*X :-), so I can allways think of some long file name, that > > I'm quite sure wont colide with other file names. > > That's odd. I thought |tempnam| _was_ a UNIXism. Yes, it is. Originally it's from SVID2, and it's listed both in XPG2 and XPG3. 'Though I don't know if BSD 4.2 has it (but mktemp() is there), at least SunOS 4.1 does support it. Cheers, Joachim PS: For the Non-Unix folks: SVID: System V Interface Definition XPG: X/Open Portability Guide Open definitions of the API for Unix systems. -- =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= Joachim Schrod Email: schrod@iti.informatik.th-darmstadt.de Computer Science Department Technical University of Darmstadt, Germany ================================================================================ Archive-Date: Wed, 22 Dec 1993 14:51:25 CST Sender: LP-Mgr@SHSU.edu From: preston@cs.rice.edu (Preston Briggs) Reply-To: LitProg@SHSU.edu, preston@CS.RICE.EDU Subject: Re: DEK's `Stanford Graph Base' book existing / available? Message-ID: Date: Wed, 22 Dec 1993 17:58:05 GMT To: LitProg@SHSU.EDU mwj@cnve.rz.uni-jena.de (Johannes Waldmann) writes: >Some time ago a new book by Knuth `The Stanford Graph Base' >was announced in some newsgroup. Is it available, meanwhile? I recently got a flyer from the ACM Press saying that it's here, order now. US$ 40.75 for ACM members, $45.25 for nonmembers. ACM order number 704931 ACM Church Street Station PO Box 12114 New York, NY 10257 (800) 342-6626 or (212) 626-0500 ACMPUBS@acm.org In Europe, ACM European Service Center Avenue Marcel Thiry 204 1200 Brussels, Belgium Phone 32 2 774 9602 ACM_EUROPE@acm.org >Is it something like his TeX/MF books, or rather like Art Of Computer >Programming? (I read it should become Vol 4 of this series.) It's not Volume 4; instead, it's supposed to represent his final preparation. Nor do I imagine it's like the TeX/MF books. They were each a single large program. This is supposed to be a collection of 30 essays, where each essay is is a small program. Preston Briggs ================================================================================ Archive-Date: Wed, 22 Dec 1993 15:20:30 CST Sender: LP-Mgr@SHSU.edu Date: Wed, 22 Dec 93 12:54:57 PST From: bos@mdd.comm.mot.com (Mary Bos) Reply-To: LitProg@SHSU.edu, bos@MDD.COMM.MOT.COM Message-ID: <9312222054.AA06943@bb04c.mdd.comm.mot.com> To: LitProg@SHSU.edu, preston@CS.RICE.EDU Subject: Re: DEK's `Stanford Graph Base' book existing / available? I bought Knuth's new book "The Stanford GraphBase" at the University BookStore (University of Washington) in Seattle, WA USA, for $42.00 US about a month ago. I have seen the book around in other bookstore's computer science areas (Tower Books - a chain in the US). The blurb on the back says "The Stanford GraphBase: A Platform for Combinatoral Computing represents the first fruits of Donald E. Knuth's preparations for Volume 4 of The Art of Computer Programming. The book's first goal is to demonstrate, through 30 examples, the art of literate programming....The book's second goal is to provide a useful means for comparing combinatorial algorithms and evaluating methods of combinatorial computing...." I have introduced a few others in my workplace to this book and seem to be getting others to consider literate programming as a standard. We'll see. mary bos bos@mdd.comm.mot.com Motorola Wireless Data Group (206) 487 5851 19807 NorthCreek Parkway North Bothell WA 98011 ================================================================================ Archive-Date: Fri, 24 Dec 1993 15:44:23 CST Sender: LP-Mgr@SHSU.edu From: bill@majipoor.cygnus.com (Bill Cox) Reply-To: LitProg@SHSU.edu, bill@MAJIPOOR.CYGNUS.COM Subject: Re: DEK's `Stanford Graph Base' book Message-ID: <42717@toad.com> Date: 23 Dec 93 00:45:14 GMT To: LitProg@SHSU.EDU I bought a copy about 2 weeks ago. It's about a set of tools that Knuth built to help him work on combinatorial problems for Volume 4. He spoke about Volume 4 at the bookstore where I bought the book. Volume 4 will be about *2000* pages, in three bindings. He expects to be done by the year 2003. John Hennesey is helping him to design a RISC-like assembly language to replace MIX. Apparently, most of the Volume 4 algorithms will be written in cweb, as the GraphBase is, but the RISC MIX will see some use. Volume 4 will be published as a series of 'fascicles' of about 128 pages, starting in the middle of 1994. I believe he said that the RISC MIX will be one of the first fascicles, so people will have time to build simulators. The GraphBase software is available free by anonymous FTP from labrea.stanford.edu. It was truly a treat to hear him speak in person. DEK's a entertaining speaker! -- bill@cygnus.com Your CHILL compiler supplier (415)903-1436 (voice) (415)903-0122 (FAX) ================================================================================ Archive-Date: Fri, 24 Dec 1993 16:45:27 CST Sender: LP-Mgr@SHSU.edu Date: Thu, 23 Dec 93 17:51:09 EST From: Lee Wittenberg Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET To: LitProg@shsu.edu, paul@opal.com.au Subject: Re: cweb for C++ API Extractor? - Request for Information Message-ID: Paul Bandler writes: > I am new to reading this group so appologies for what is I'm sure a very > basic question. No apologies necessary. That's what the group is for (IMHO). > We're at the begining for a C++ development and establishing coding / > documentation practises for the project. We would like to be able to > build a high quality (i.e. to be distributed as part of a software product) > programmer's reference manual derived from the C++ source files. > > In investigating this I have been lead to this news group and understand > that there is a program called cweb which may be of assistance to us. > > Could someone advise:- > > 1. Whether cweb is a tool suitable to my purpose? Yes. CWEB 3.0 (and thus the current version 3.1, as well) is designed to work with C++. I have used it for some C++ work myself. > 2. Is cweb available in the public domain at an archive site? If so, > where? The official site is labrea.stanford.edu. I believe it is in the ~/pub/cweb directory. > 3. Would someone be willing to send me an example cweb input and output > so that I can get an idea of what is involved? CWEB itself is just such an example, but if you'd like something simpler, I have a few sample webs available in the ~/pub/leew/samples.LP directory of bart.kean.edu. > 4. Would it be possible to integrate cweb with Framemaker? It ~may~ be possible, if you're willing to do the rewriting, but CWEB is set up (designed?) to work with TeX. > 5. There is some resistance here to the effect of needing to instrument > ones source code extensively in order to be able to create product > quality end-user documentation from it. Can anyone comment as the > feasibility/desirability of this approach or indicate whether this > has been achieved successfully in practice somewhere? LP doesn't really work well for end-user documentation (IMHO). What it ~does~ do is to turn the program itself into a high-quality programmer's reference (which is what you asked about in the first place). > I would appreciate any respondants copying me directly by email in order to > ensure timely delivery. Hope this helps. -- Lee leew@pilot.njin.net ================================================================================ Archive-Date: Sun, 26 Dec 1993 00:14:23 CST Sender: LP-Mgr@SHSU.edu From: thompson@sun1.coe.ttu.edu Subject: comp.programming.literate FAQ Date: 26 Dec 1993 00:00:25 -0500 Message-ID: Reply-To: LitProg@SHSU.edu, thompson@sun1.coe.ttu.edu To: LitProg@SHSU.EDU Archive-name: literate-programming-faq Last-modified: 1993/11/11 Version: 1.0.4 Welcome to the Literate Programming Frequently Asked Questions List ------------------------------------------------------------------- This version was created Thursday - November 11, 1993 and should considered stale after 90 days. Information contained in this document is the best available at preparation. Disclaimer: "This FAQ is presented with no warranties or guarantees of ANY KIND including correctness or fitness for any particular purpose. The author of this document has attempted to verify correctness of the data contained herein; however, slip-ups can and do happen. If you use this data, you do so at your own risk." Copyright 1993 David B. Thompson. All rights reserved worldwide. Permission is granted to copy this document for free distribution so long as it remains intact and unmodified. = ====================================================================== * Introduction: --------------- This document is for new and experienced users of literate programming tools. The purpose is to explain the concept of literate programming and to provide a resource for locating files of interest to literate programmers and those interested in literate programming. The Literate Programming (LitProg) Frequently Asked Questions (FAQ) list is maintained by Dave Thompson, who can be reached at: thompson@sun1.coe.ttu.edu * Preferred mailing address for FAQ related comments/questions. wqdbt@ttacs1.ttu.edu * Forwarded to my pc. Comment and constructive criticism is welcome. Direct flames to /dev/null (or > nul if you're a msdos user! ;-) If you find an error, please report it. I'm particularly interested in establishing the locations of generally available literate programming tools. If you are the author of such a tool and wish to have it included in this list, please send email. Please note this is a work-in-progress. It is *not* complete, and probably will not be complete for some months. Nevertheless, the information contained herein may be useful to some. Use it as it is intended. - ---------------------------------------------------------------------- - Typography: ------------- Major sections of the FAQ are divided by double lines (====). Minor sections and other divisions are separated by single lines (----). Major topics use a "* " as a leader. Minor topics use a "- " as a leader. This should simplify searching for topics. = ====================================================================== Table of Contents: ------------------ * Introduction - Typography. * How to get the FAQ. - Literate Programming FAQ. - FWEB FAQ. * The LitProg newsgroup. * Internet nodes of interest to literate programmers. * What is literate programming? * How do I begin literate programming? * What tools are available and where are they? - c2latex - CLip - CWEB - FunnelWeb - FWEB - noweb - NUWEB - SchemeWEB - Spidery WEB - WinWordWEB * What other resources are available? - Virtual Coursework * Code examples. - Examples included with developer's tools - Cameron Smith's KR-CWEB - Bart Child's examples for FWEB * Bibliographies. * How to anonymously ftp. * Acknowledgements. * End notes. = ====================================================================== * How to get the FAQ: --------------------- - Literate Programming FAQ. --------------------------- You have many ways to get a current copy of this FAQ. One is to use anonymous ftp (if you don't know how, see a later section in this FAQ) to connect to one of the Comprehensive TeX Arvchive Network (CTAN) sites or the Literate Programming Archive and retrieve a copy of the file. (For more information on CTAN and the literate programming archive, see the section below entitled "Internet Nodes of Interest to Literate Programmers.") An alternative is to use the fileserver at SHSU. Send a message to FILESERV@SHSU.EDU (FILESERV@SHSU.BITNET) and include in your message SENDME FAQ.LITPROG The file server will forward a copy of the file to you via email. - ---------------------------------------------------------------------- - FWEB FAQ: ----------- Marcus Speh maintains the FWEB FAQ. The current version number is 1.29. It can be retrieved in the same way as this FAQ; either by anonymous ftp or through the SHSU file server. On the SHSU server, the file name is FAQ.FWEB. Invoke your ftp software, open a connection to NIORD.SHSU.EDU [192.92.115.8], attach to the directory FAQ, and transfer the file FAQ.FWEB. Alternatively, send a message to the file server, FILESERV@SHSU.EDU (FILESERV@SHSU.BITNET), and include the following text in a one line message: SENDME FAQ.FWEB The file server will send the current version of the file via email. The FWEB FAQ exists in various formats, including HyperText (see other resources below). In Europe, the complete distribution can also be obtained from ftp.desy.de [131.169.10.115] in directory /pub/faq/web/fweb/. It is also available from the literate programming archive (LPA) in the directory LPA/documentation/faq/fweb (see the references to LPA below for more information). = ====================================================================== * The LitProg Newsgroup: ------------------------ One of the most important resources is the literate programming newsgroup, comp.programming.literate. You can read this newsgroup using your standard reader. Altenatively, the newsgroup is gated to a mailing list hosted by George Greenwade and Sam Houston State University. You can subscribe by sending mail to the list-server, LISTSERV@SHSU.EDU (or LISTSERV@SHSU.BITNET), and include in the message one line of text: SUBSCRIBE LITPROG "your name in quotes" The list is unmoderated; messages sent to litprog@shsu.edu are automatically distributed to all subscribers and cross-posted to comp.programming.literate. Archives of the mailing list and newsgroup are maintained on niord.shsu.edu [192.92.115.8] in the directory litprog. = ====================================================================== * Internet Nodes of Interest to Literate Programmers: ----------------------------------------------------- The principal nodes of interest to literate programmers are the Literate Programming Archive (LPA hereafter) and the CTAN (Comprehensive TeX Archive Network). The Literate Programming Archive (LPA) is: Node: ftp.th-darmstadt.de [130.83.55.75] Directory: pub/programming/literate-programming Notes: Fastest response during off-U.S. [yep] business hours. The CTAN sites are: ftp host IP CTAN root Institution and Sponsor ------------------------------------------------------------------------- ftp.TeX.ac.UK 134.151.79.32 pub/archive Aston Univ./UK TeX U.G. ftp.Uni-Stuttgart.DE 129.69.8.13 soft/tex Univ. Stuttgart/DANTE e.V ftp.SHSU.edu 192.92.115.10 tex-archive Sam Houston State Univ. Other nodes and directories of interest include: Node: niord.shsu.edu [192.92.115.8] Directory: various (do some snooping!) Notes: Has a gopher server. Node: ftp.desy.de [131.169.10.115] Directory: pub/web. Various documents, samples, and the FWEB FAQ. Notes: Has a www server, http://info.desy.de:80/ = ====================================================================== * What is Literate Programming? ------------------------------- Literate programming is the combination of documentation and source together in a fashion suited for reading by human beings. In fact, literate programs should be enjoyable reading, even inviting! (Sorry Bob, I couldn't resist!) In general, literate programs combine source and documentation in a single file. Literate programming tools then parse the file to produce either readable documentation or compilable source. The WEB style of literate programming was created by D.E. Knuth during the development of his TeX typsetting software. All the original work revolves around a particular literate programming tool called WEB. Knuth says: The philosophy behind WEB is that an experienced system programmer, who wants to provide the best possible documentation of his or her software products, needs two things simultaneously: a language like TeX for formatting, and a language like C for programming. Neither type of language can provide the best documentation by itself; but when both are appropriately combined, we obtain a system that is much more useful than either language separately. The structure of a software program may be thought of as a web that is made up of many interconnected pieces. To document such a program we want to explain each individual part of the web and how it relates to its neighbours. The typographic tools provided by TeX give us an opportunity to explain the local structure of each part by making that structure visible, and the programming tools provided by languages such as C or Fortran make it possible for us to specify the algorithms formally and unambigously. By combining the two, we can develop a style of programming that maximizes our ability to perceive the structure of a complex piece of software, and at the same time the documented programs can be mechanically translated into a working software system that matches the documentation. = ====================================================================== * How to begin literate programming: ------------------------------------ A recommended book is D.E. Knuth's collection of articles (1992) "Literate Programming," Center for the Study of Language and Information, Stanford University, ISBN 0-937073-80-6 (pbk). This book gives insight into Knuth's thoughts as he developed the web system of literate programming (and TeX for typesetting). It does not document methods for literate programming. A recommended book is Wayne Sewell's (1989) "Weaving a Program: Literate Programming in WEB," Van Nostrand Reinhold, ISBN 0-442-31946-0 (pbk). This book focuses on using Knuth's web system. Some talk exists in the newsgroup/mailing list for a Usenet University course in literate programming. I'm sure discussion of this topic will be welcomed. If you are interested, please participate. = ====================================================================== * What Tools are Available: --------------------------- A significant number of tools for literate programming are available. Most have been ported from their original systems, so support multiple computer platforms. If you are the developer of such a tool, and would like to make the software freely available, please send me email and I'll reply with a form (like those below) for you to fill in. (Or short-circuit the process and kludge a form from below. :-) - C2LaTeX: ---------- Developer: John D. Ramsdell System(s) supported: Unix Software supported: Programming language: C. Text formatter: LaTeX but it's easy to change the formatter. Availability: Anonymous ftp from omnigate.clarkson.edu:/pub/tex/tex-programs/c2latex. Readme: Absent. Documentation is in the C source for c2latex. Brief description: C2latex provides simple support for literate programming in C. Given a C source file in which the comments have been written in LaTeX, c2latex converts the C source file into a LaTeX source file. It can be used to produce typeset listings of C programs and/or documentation associated with the program. C2latex produces LaTeX source by implementing a small number of rules. A C comment that starts at the beginning of a line is copied unmodified into the LaTeX source file. Otherwise, non-blank lines are surrounded by a pair of formatting commands (\begin{flushleft} and \end{flushleft}), and the lines are separated by \\*. Each non-blank line is formatted using LaTeX's \verb command, except comments within the line are formatted in an \mbox. Support: Send bug reports to ramsdell@mitre.org. - ---------------------------------------------------------------------- - CLip: ------- Developer: E.W. van Ammers and M.R. Kramer Systems supported: Vax/VMS and MS-DOS. Software supported: An programming language. Plain TeX and LaTeX text formatters. Availability: Anonymous ftp from: CTAN/web/clip LPA/machines/ms-dos LPA/machines/vax sun01.info.wau.nl/CLIP Readme: In distribution. Brief description: Support: Unknown. - ---------------------------------------------------------------------- - CWEB: ------- Developer: Silvio Levy and D.E. Knuth System(s) supported: Unix systems (dos and amiga ports available) Software supported: Languages supported are C and C++. Text formatters are plain TeX and LaTeX. Availability: anonymous ftp from: labrea.stanford.edu/pub/cweb LPA/c.c++ CTAN/web/c_cpp/cweb DOS version in CTAN/web/c_cpp/cwb30p8c DOS version in LPA/machines/ms-dos Amiga version to be posted soon (look at CTAN). Mac port of CTANGLE in LPA/machines/mac LaTeX support in LPA/c.c++ Readme: bundled with above Brief description: Support: bugs to levy@math.berkeley.edu - ---------------------------------------------------------------------- - FunnelWeb: ------------ Developer: Ross N. Williams: ross@guest.adelaide.edu.au Systems supported: MSDOS, Mac, VMS, Sun. Other ports reported. Software supported: For printing, TeX. Otherwise no restrictions. Availability: anonymous ftp from: CTAN/web/funnelweb LPA/independent ftp.adelaide.edu.au/pub/funnelweb Readme: With bundle above. Brief description: FunnelWeb is a production-quality literate-programming tool that emphasises simplicity and reliability. Everything about FunnelWeb, from the simplicity of its language to the comprehensive tutorial in the user's manual, has been designed to make this as simple, as practical, and as usable a tool as possible. Features: + Provides a simple macro preprocessor facility. + Can produce typeset documentation. + Runs on Sun, VMS VAX, Macintosh, PC, and others. + Portable C source code distributed under GNU licence. + Comprehensive user's manual including tutorial. + Programming-language independent. + Can generate multiple output files. + Allows complete control over the output text. + Regression test suite with over 200 tests. + Fully worked example (in /pub/funnelweb/examples). - Requires TeX to produce typeset documentation. - Typesets program code using TT font only. Support: No formal support available. Mailing list maintained with about 50 subscribers. Informal assistance available from mailing list. - ---------------------------------------------------------------------- - FWEB: ------- Developer: John A. Krommes System(s) supported: Unix and DOS platforms Software supported: C, C++, Fortran-77, Fortran-90, Ratfor, TeX, and LaTeX. Text formatters are plain TeX and LaTeX. Availability: anonymous ftp from: lyman.pppl.gov/pub/fweb CTAN/web/fweb LPA/fweb DOS version in LPA/machines/ms-dos Readme: In bundle with above. Brief description: It also has a well-developed user's manual and its own FAQ (see above). It runs on most platforms: VMS, PC, UNIX, and pretty much anything that the GNU C compiler (GCC) is supported for. Support: bug reports to krommes@princeton.edu - ---------------------------------------------------------------------- - noweb: -------- Developer: Norman Ramsey System(s) supported: Unix and DOS platforms Software supported: All programming languages, plain TeX and LaTeX formatters. Availability: anonymous ftp from: csservices.princeton.edu/pub/noweb.shar.Z bellcore.com/pub/norman/noweb.shar.Z CTAN/web/independent/noweb LPA/independent Readme: with bundle above Brief description: noweb is designed to meet the needs of literate programmers while remaining as simple as possible. Its primary advantages are simplicity, extensibility, and language-independence. noweb uses 5 control sequences to WEB's 27. noweb now supports indexing and identifier cross-reference. The simple noweb manual is only 2 pages; documenting the full power of noweave and notangle requires another 3 pages. noweb works ``out of the box'' with any programming language, and its formatter-dependent part is a 60-line nawk program. The primary sacrifice relative to WEB is the loss of prettyprinting. Support: by email to the author - ---------------------------------------------------------------------- - NUWEB: -------- Developer: Preston Briggs: preston@cs.rice.edu Systems supported: Unix systems; Sparcs, RS/6000s, HPs, and (!) MSDOS. Software supported: It's written in C. It works with any programming language (or combination of programming languages) and uses Latex as its text formatter. Availability: anonymous ftp from: Unix: CTAN/web/nuweb DOS: CTAN/web/nuweb-pc LPA/independent Readme: Send mail to preston@cs.rice.edu Brief description: A single program that takes a web file written in a combination of latex and any programming language(s) and produces a latex file that can be pretty printed and a set of files containing code for compilation/interpretation by the appropriate language processors. Strengths include speed, simplicity, multiple languages, nice indices and cross-references, latex. Doesn't require any special macros or macro files. Drawbacks: latex-dependent, no code pretty printing, harder to make indices than cweb. More good stuff: nice support for make, doesn't reformat source files, so they're easy to debug. Lots of control without too much effort. That is, it doesn't do too much! Future directions... Very little change planned, except perhaps refinements in the indexing software. Support: Hack it yourself or send e-mail to preston@cs.rice.edu - ---------------------------------------------------------------------- - SchemeWEB: ------------ Developer: John D. Ramsdell System(s) supported: Unix and DOS platforms Software supported: Programming language: Any dialect of Lisp. Text formatter: LaTeX. Availability: The Unix version is in the Scheme Repository and it is available via anonymous ftp from: nexus.yorku.ca/pub/scheme/utl LPA/lisp The DOS version is part of the PCS/Geneva Scheme system which is available via anonymous ftp from: cui.unige.ch/pub/pcs. LPA/machines/ms-dos Readme: In bundle with above. Brief description: SchemeWEB is a Unix or DOS filter that translates SchemeWEB source into LaTeX source or Lisp source. Lisp code is formatted in typewriter type font and the comments are passed to LaTeX unchanged. Support: Send bug reports to ramsdell@mitre.org. - ---------------------------------------------------------------------- - Spidery WEB: ------------- Developer: Norman Ramsey System(s) supported: Unix and DOS platforms Software supported: Most Algol-like languages, including C, Ada, Pascal, Awk, and many others. Plain TeX and latex for text formatters. Availability: Anonymous ftp from: CTAN Readme: In distribution. Brief description: A system for building language-dependent WEBs. Spider is frozen; no further development is planned. Support: Bug reports to author. - ---------------------------------------------------------------------- - WinWordWEB: ------------- Developer: Lee Wittenberg Systems supported: Needs Microsoft Word for Windows, v.2.x, and, of course, MS-Windows 3.x. Software supported: Any programming language. Word for Windows 2.x for text formatting and file maintenance. Availability: anonymous ftp from: bart.kean.edu:pub/leew World-Wide Web (WWW) Readme: WORDWEB.DOC in the downloadable package describes the system. Brief description: WinWordWEB is a set of a Word for Windows macros (plus a paragraph style) that provide a crude literate programming environment. The ``look and feel'' of the system is based on Norman Ramsey's noweb, but can easily be modified to suit individual tastes. Support: None. WinWordWEB was written as a prototype to see if a WYSIWYG literate programming system was possible. It is intended as a jumping off point for future work by others. However, the system is surprisingly usable as it stands, and the author is interested in hearing from users (satisfied and unsatisfied). Anyone interested in actively supporting (and improving) the product should contact the author via email. = ====================================================================== * Other resources: ------------------ An untapped resource (by me anyway ;-) is the World Wide Web. Marcus Speh has expended considerable effort in this regard. If you're connected to WWW, then access: http://info.desy.de/user/projects/LitProg.html If you aren't connected to WWW, telnet to info.cern.ch and explore. You can reach Marcus' literate programming pages by typing: go http://info.desy.de/user/projects/LitProg.html Help for people who have only Email and neither WWW nor telnet, can be obtained by Email from LISTSERV@INFO.CERN.CH by sending a message containing the command HELP. Instructions will be returned by email. For literate programming documents, you can try anonymous ftp to ftp.desy.de [131.169.10.115] and attach to directory: /pub/userWWW/projects/Announce Another resource of interest to literate programmers is the info-tex mailing list. If you're using (La)TeX as your typsetting system and have access to internet, then you should investigate this mailing list. Mail list service is available through the SHSU list-server. To subscribe, send a message to LISTSERV@SHSU.EDU (LISTSERV@SHSU.BITNET), and include in the message one line of text: SUBSCRIBE INFO-TEX "your name in quotes" The list is unmoderated; messages sent to info-tex@shsu.edu are automatically distributed to all subscribers and cross-posted to comp.text.tex. Archives of the mailing list and newsgroup are maintained on niord.shsu.edu [192.92.115.8] in the directory info-tex. - ---------------------------------------------------------------------- - Virtual Coursework: --------------------- Marcus Speh plans an introductory course on Literate Programming on the Internet, part of the first semester of "Global Network Academy" [GNA], a non-profit corporation incorporated in the state of Texas, affilated with the Usenet University project. The texts/sample programs for this class will be made available via anonymous FTP. A special room on GNA Virtual Campus will be staffed by a consultant in one to two hour shifts. Students with questions can telnet to the virtual campus and ask questions of the staff there. Tuition: Students should agree to work for Global Network Academy in some capacity. This may include agreeing to serve as a consultant next term, donating computing resources which belong to them, helping with programming, etc. If you are interested in registering for the course either as a student or as a consultant, please contact marcus@x4u.desy.de. You will receive a standard reply message; no further action will be taken until January 94. [Editor's note: Because of workload, Marcus requests that email inquiries be limited to a statement of interest for either a student or consultant position until January 1994.] = ====================================================================== * Code Examples: ---------------- Examples of web programs are included with the FWEB, CWEB, and noweb distributions. Cameron Smith converted the K&R calculator program into a literate program. It can be retrieved by anonymous ftp from: niord.shsu.edu [192.92.115.8] directory kr-cweb-sample as krcwsamp.zip or from LPA/Documentation Ross Williams has released a funnelweb example. You can retrieve this file from node ftp.adelaide.edu.au [129.127.40.3] as /pub/funnelweb/examples/except.* This file should be on CTAN as well. = ====================================================================== * Bibliographies: ----------------- Nelson Beebe has collected an extensive bibliography treating literate programming. His work is available for anonymous ftp from ftp.math.utah.edu [128.110.198.2] in directory /pub/tex/bib as files: litprog.bib litprog.ltx. Although I have not verified this, LPA is an alternate source for these files. Note that they are updated frequently (Nelson says several times each week), so be sure to get a fresh copy before extensive use. Joachim Schrod indicates that these files may be updated daily and can be retrieved via anonymous ftp at LPA/documentation. = ====================================================================== * How to anonymously ftp: ------------------------- Pretty much everything mentioned here is available by anonymous FTP. FAQ lists cross-posted to news.answers and rec.answers can be gotten from rtfm.mit.edu [18.70.0.209], under /pub/usenet/news.answers or under /pub/usenet/more.specific.group.name "anonymous FTP" is just a way for files to be stored where anyone can retrieve them over the Net. For example, to retrieve the latest version of the literate programming FAQ, do the following: > ftp rtfm.mit.edu /* connect to the site; message follows */ > anonymous /* type this when it asks for your name */ > /* type your address as the password */ > cd /pub/usenet /* go to the directory you want to be */ > cd comp.programming.literate /* one level down (no slash). */ > dir /* look at what's there */ > get literate-progamming-faq /* get the file; case-sensitive */ > quit /* stop this mysterious thing */ If your FTP program complains that it doesn't know where the site you want to use is, type the numerical address instead of the sitename: > ftp 18.70.0.209 /* connect with numerical address */ If you don't have ftp access, send e-mail to mail-server@rtfm.mit.edu with the single word "help" in the body of the message. Getting binary files (executables, or any compressed files) is only slightly more difficult. You need to set binary mode inside FTP before you transfer the file. > binary /* set binary transfer mode */ > ascii /* set back to text transfer mode */ FAQs and spoiler lists are generally ascii files; everything else is generally binary files. Some common extensions on binary files in archive sites are: .Z Compressed; extract with uncompress .tar.Z Compressed 'tape archive'; uncompress then untar or tar -xvf .gz or .z Gnu gzip; use gunzip (available from prep.gnu.ai.mit.edu) .sit (Mac) StufIt archive .zip Extract with Zip or Unzip .zoo Yet another archive/compress program .lhe (Amiga) ? .lzh Lha archive program. .arj (PC) Arj archive program. .exe (PC) Sometimes self-extracting archives-just execute them. .uue or .UUE Transfer as text file; use uudecode to convert to binary .hqx (Mac) BinHex format; transfer in text mode Generic help can be found in the FAQs of comp.binaries. for how to transfer, extract, and virus-check binary files. (At rtfm.mit.edu) If you can't FTP from your site, use one of the following ftp-by-mail servers: ftpmail@decwrl.dec.com ftpmail@src.doc.ic.ac.uk ftpmail@cs.uow.edu.au ftpmail@grasp.insa-lyon.fr For complete instructions, send a message reading "help" to the server. If you don't know exactly what you're looking for, or exactly where it is, there are programs and servers that can help you. For more info, send e-mail to mail-server@rtfm.mit.with with the body of the message reading send usenet/news.answers/finding-sources Thanks to Aliza R. Panitz (the "buglady") for this text. I copied it verbatim from her post on faq-maintainers with only minor modifications. = ====================================================================== * Acknowledgements: ------------------- This document would not have happened without the help of many people. Among them are Marcus Speh, George Greenwade, Rob Beezer, Joachim Schrod, Piet van Oostrum, and Ross N. Williams. A special thanks to Aliza R. Panitz for the text describing how to execute an anonymous ftp for files of interest. Any omissions from these acknowledgements should be considered an act of stupidity on my part. Of course, the authors of literate programming tools mentioned above all play a vital role in the vitality of literate programming. Furthermore, participants in the comp.programming.literate newsgroup (and associated mailing list) all contributed in various fashions. Thank all of you. = ====================================================================== * End notes: ------------ This document will be evolving over the next few months. I'm planning on adding entries for additional literate programming tools and will expand the sections on examples as more examples become available. Tools I will include are web (the original pascal version), funnelweb, spiderweb, and cnoweb for starters. Others will be added as I find and document them. Omission of a particular tool should not be considered a snub in any sense--simply an error or oversight on my part. History: First release: Fri 10/15/1993 -- Yep, I finally did it! Thu 10/21/93 -- Minor change to ftp instructions. Fri 10/22/93 -- Minor change to stuttgart ip and fweb.faq version. Made reader-recommended changes, lots of re- organization, and added a few tools. Mon 11/01/93 -- Corrected typo in address. Thu 11/11/93 -- Minor change to www. = End of File ========================================================== ================================================================================ Archive-Date: Fri, 31 Dec 1993 17:57:39 CST Sender: LP-Mgr@SHSU.edu From: schrod@iti.informatik.th-darmstadt.de (Joachim Schrod) Reply-To: LitProg@SHSU.edu, schrod@ITI.INFORMATIK.TH-DARMSTADT.DE Subject: Contents of the LitProg Archive (monthly posting) Date: 1 Jan 1994 00:20:04 +0100 Message-ID: <2g2c34INNbrn@spice.iti.informatik.th-darmstadt.de> To: LitProg@SHSU.EDU # literate-programming/Contents 20 Dec 93 -*- Indented-Text -*- #------------------------------------------------------------ The material available from the Literate Programming Archive is categorized, each category is put in a directory tree. While this structure (which is described in the README files) supports browsing, the need for quick access to a specific Literate Programming tool remains. This file shall assist you in this need. It presents the *WEB systems and tools available, in an alphabetic order, and names the directory where you can find it. In addition to the systems mentioned below, the LitProg Archive features texts in the directory Documentation: FAQs, papers, and an extensive bibliography in BibTeX format. Since this file is updated manually, I cannot guarantee that it's up to date. Send reports about inconsistencies of description and reality to Joachim Schrod . SYSTEM DIRECTORY REMARK ------ --------- ------ APLWEB apl w/o source, but under the GPL! [this was an error by the author] AWEB ada/aweb not supported any more cfa Tools Change File Analyzer CLiP any language, any formatter, any -- for DOS machines/ms-dos wordprocessor. Hypertext -- for VMS machines/vms integration possible cnoweb c.c++ CWEB (Levy/Knuth) C++, ANSI C, K&R C -- source c.c++ -- DOS port machines/ms-dos -- Mac port machines/mac/cweb only CTANGLE cweb style c.c++ CWEB programs as LaTeX documents CWEB (van Leeuwen) c.c++ CWEB for ANSI C, in ANSI C CWEB (Schrod) not supported any more send me mail if you have historic interests :-) Funnelweb independent FWEB multi-lingual WEB -- source fweb -- DOS port machines/ms-dos Knit pascal not supported any more lit2x independent [????] from Glasgow LPW machines/mac Literate Programming Workshop CAVEAT: Shareware! MapleWEB maple [SpiderWEB?] MWEB (Schrod/Detig) modula-2 not supported any more MWEB (Sewell) modula-2 not supported any more noweb uses the UNIX toolbox paradigm -- source independent -- DOS port machines/ms-dos ProTex independent WEB system based on TeX RWEB reduce [SpiderWEB?] SpiderWEB WEB generator, in awk -- source spiderweb -- DOS port machines/ms-dos -- OS/2 port machines/os2 -- Mac port machines/mac TIE Tools Change File Merger WEB The basis, it started with it... -- source pascal -- DOS port machines/ms-dos WEB mode Tools for GNU Emacs WinWordWEB machines/ms-dos WEB with Word for Windows Systems without support of refinements -------------------------------------- MAKEPROG independent is here for my own convenience :-) SchemeWEB lisp -- =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= Joachim Schrod Email: schrod@iti.informatik.th-darmstadt.de Literate Programming Archive, maintainer Technical University of Darmstadt, Germany ================================================================================ Archive-Date: Fri, 31 Dec 1993 20:10:39 CST Sender: LP-Mgr@SHSU.edu Message-ID: Date: Fri, 31 Dec 93 18:10 PST To: LitProg@SHSU.EDU Subject: Whew... I'm back. From: Kayvan Sylvan Reply-To: LitProg@SHSU.edu, kayvan@SATYR.SYLVAN.COM I've just read about 5 megabytes of litprog mail. It's taken me a while to get back to LitProg, since work and family matters got in the way. With the perspective gained from reading 4 months of archives in a couple of days, I have some thoughts to share. :-) 1. There's still too little sharing of real-world literate programs and techniques. I want to see more code being posted and more peer review going on. I don't really know whether the literate Perl, Prolog, C, C++, or Lisp code I write is good literate programming, because I haven't gotten too many comments other than "Wow. Cool. Looks nice." I suspect there are other literate programmers who are hungry for constructive criticism of their publications and I think that the LitProg mailinglist/newsgroup can be a forum for this. 2. Along the same lines as #1, I want to see a document that is a set of style guidelines or useful suggestions for literate programming. There has been talk along this line at various times, but no one has stepped forward to coordinate this. This document would answer general literate programming questions like "How do I structure my C++ WEB to make the interface obvious for users of the contained classes but still document the implementation in a sensible way?" I'd be willing to collect bits of advice and/or guidelines and compile it into a LitProg suggestions document in my copious spare time. It's good to be "back" (I never really went anywhere, but it feels like I'm returning). Happy New Year to all!!! ---Kayvan | Kayvan Sylvan, Sylvan Associates, kayvan@satyr.Sylvan.COM, (408) 978-1407 | | Consulting, Training, Development, SysAdmin, {BSD,SVr3,SVr4} Unix Systems | | "Think Globally, Act Locally." "Only you can make your dreams come true." | | Proud Dad of Katherine Yelena (born 8/8/89) & Robin Gregory (born 2/28/92) |