Archive-Date: Sat, 01 Oct 1994 11:02:54 CDT Sender: owner-litprog@SHSU.edu From: wjmackey@netcom.com (WILLIE J MACKEY) Reply-To: LitProg@SHSU.edu, wjmackey@NETCOM.COM Subject: BLACK DATA PROCESSING ASSOCIATES Message-ID: Date: Sat, 1 Oct 1994 05:56:50 GMT To: LitProg@SHSU.EDU National Black Data Processing Associates Information Sheet -------------------------------------------------------------------------- National Black Data Processing Associates BDPA Silicon Valley Chapter 1250 Connecticut Avenue NW, Suite 610 370 Altair Way #124 Washington DC 20036-2603 Sunnyvale, CA 94086-6161 1-800-727-BDPA [voicemail] 1-408-746-4843 1-202-775-4301 [voice/fax] 1-408-280-7624 info@bdpabac.com wjmackey@bdpabac.com wjmackey@netcom.com BDPA HISTORY ------------ In May of 1975, Earl A. Pace Jr. and David Wimberly founded, on a local basis, the non-profit organization Black Data Processing Associates. In 1979, BDPA was restructured as a national organization with chapters in Philadelphia, Washington, DC and Cleveland, Ohio. Today, the BDPA national organization is represented nationally by over 50 local chapters and 1600 members! MISSION STATEMENT ----------------- The mission of BDPA is to sustain a network of information technology professionals that is a positive influence in the information processing industry; a network which shares information, provides education and performs community service. BDPA OBJECTIVE -------------- On a local and national level, the primary objective of BDPA is to accumulate a pool of information processing knowledge and business expertise with the intention of utilizing those resources to: * Support the interest of those individuals examining the field of information processing as a career or business opportunity. * Provide a forum for the development of interests and skills of the minority community as a whole. * Participate actively in the events supporting the aims of the information processing industry. ACTIVITIES AND PROGRAMS ----------------------- On a local level, BDPA uses vehicles such as panel discussions, guest speakers, general meetings, and workshops to fulfill its objectives. On a national level, BDPA sponsors a National Conference which includes: High School Computer Competition, technical and professional development programs and information processing industry exhibits. BDPA EDUCATION AND TECHNOLOGY FOUNDATION ---------------------------------------- Since 1975, Black Data Processing Associates (BDPA) has been educating and training minority professionals working within the information technology industry. BDPA has successfully reached out to many, and has provided opportunities through networking, educational programs, monthly seminars, monthly workshops and annual conferences. Educational and technical opportunities still reach the African American community at a slow pace. BDPA has a larger task and broader range of people (especially youth) to reach. Recognizing the need for accelerated action, the BDPA Education and Technology Foundation (BDPA Foundation) was established. The BDPA Foundation is a nonprofit, tax exempt organization whose sole purpose is to fund the education and technology projects of the National Black Data Processing Associates local chapters. The BDPA Foundation is a catalyst for lasting social change. The Foundation invests in a broad range of innovative solutions for the myriad of problems and opportunities that are faced. The challenges faced by the BDPA membership and the African American community remain many and great. The Foundation realizes the need for investment of a greater portion of time and efforts in youth due to the lack of exposure to information technology. The BDPA Foundation has been successful in the creation of specialized programs which advance the skills needed by youth to compete in today's wave of new technology. However, financial support is needed of BDPA members, friends, supporters, corporations and the community to continue these programs: * Adopt-a-school, a partnership with local schools created to provide tutorial and mentorship programs for students interested in information technology. * Computer Literacy, which introduces computer science to students who have little or no computer literacy skills, while also developing their interpersonal skills. * Computer Training Centers, which provides training, mentorship and career development programs to the community base promoting the need for computer literacy. * Computer Workshops, which offers members, youth and the community training in computer applications for career development. * High School Computer Competition, an intense student training program which promotes academic competition in computer science, stimulates greater interest in information technology and introduces the "team concept" used in government and corporate industries. * Mentorship Programs, which teams students with information technology professionals to provide career guidance. * Youth Mini-Conferences, which offer conferences and seminars geared towards preparing local high school students for institutions of higher education, general employment and entrepreneurial endeavors. BDPA Education and Technology Foundation is a 501(c)3 educational organization, and gifts or contributions are tax deductible. [ End of file: BDPAINFO.TXT - BDPA Information Sheet - info@bdpabac.com ] ================================================================================ Archive-Date: Sat, 01 Oct 1994 12:43:18 CDT Sender: owner-litprog@SHSU.edu From: brothers@mdd.comm.mot.com (Joseph Brothers) Reply-To: LitProg@SHSU.edu, brothers@MDD.COMM.MOT.COM Subject: Re: Nonliterate (Illiterate :-) to literate Date: 30 Sep 1994 10:59:34 -0700 Message-ID: <36hjm6$9u@bb13c.mdd.comm.mot.com> BCC: To: LitProg@SHSU.EDU I too find it practical to incorporate a Makefile in my noweb document for large, non-obvious or complex works (anything that takes a compile or tricky formatting for multiple file types or executing integral test scripts, or...). The Makefile can drive document preparation as well as software production. Using multiple targets, it can prepare different file types to be presented in the literate document's typeset output. The example that follows shows how an applications' man page source, written in [[nroff -man]], can be made to appear alongside its readable version within the typeset book. It is excerpted from a 260-page book containing the client of a time recording application. In my opinion, side-by-side source and sample output of the man page is sufficiently explanatory to need no additional description. Note the noweb extension, "\include{tsmanpag.nw}". That's my own small contribution - sent to Norman Ramsey for possible future inclusion in noweb. One gives the command "noweb tsclient.nw", then "make Makefile", then "make TimeSheet.n" to produce the man page, then "make tsclient.dvi" to view the typeset version onscreen, and "make hardcopy" to print 2-up on a Postscript printer. This is all discussed in the README, also incorporated in the document as a chunk. It's the nroff -man TimeSheet.n | colcrt - >> tsmanpag.nw that puts readable [[nroff -man]] output into the document. The [[{verbatim}]]'s preserve the work [[nroff]] did. Putting this pile of schlumpf in the Makefile keeps it handy and synchronizable. Putting the Makefile in [[noweb]] retains the possibility of understanding it three months from now. ______________________________example__________________________________ \section{Make File} Here's an excerpt from the complete project make file. <>= .nw.tex: noweave -n $? > $*.tex tsclient.tex: tsclient.nw tsusrifc.nw tsdbcomm.nw tsloclio.nw tswindow.nw tshlptxt.nw tsmanpag.nw ./noweb tsclient.nw tsclient.dvi: tsclient.tex latex $? noindex $? mv tsclient.nwi temp.nwi ; sort -u temp.nwi > tsclient.nwi ; rm temp.nwi latex $? xdvi tsclient hardcopy: tsclient.dvi dvips -Pswi tsclient -o '!psnup -l -2 | lpr -Psw1' TimeSheet.n: notangle -filter incp -RTimeSheet.n tsclient.nw > TimeSheet.n echo "\begin{verbatim}" > tsmanpag.nw nroff -man TimeSheet.n | colcrt - >> tsmanpag.nw echo "\end{verbatim}" >> tsmanpag.nw @ \section{TimeSheet References} The TimeSheet application is documented by a System Requirements Specification and a man page. The TimeSheet man page is reproduced below. \section{TimeSheet Man Page} \include{tsmanpag.nw} \section{Man Page Source} <>= .TH TimeSheet 1 "8/12/94" " " " " \" \" \" .SH NAME TimeSheet \- engineers' time tracking tool .SH SYNOPSIS .B TimeSheet .SH DESCRIPTION .PP .I TimeSheet is an online tool for recording and tracking a software engineer's time by project and task. As of version 0.976, it runs only on Sun Sparcs under the X windowing system. It will not run under SunView, nor on a Sun 3. @ -- Joseph L. Brothers brothers@mdd.comm.mot.com uunet!mdisea!brothers "I am speaking solely for my self, not my employer." ================================================================================ Archive-Date: Sun, 02 Oct 1994 09:20:02 CDT Sender: owner-litprog@SHSU.edu Date: Sun, 2 Oct 94 10:19:33 EDT From: Lee Wittenberg Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET To: LitProg@shsu.edu, jsrobin@afterlife.ncsc.mil Subject: Re: Makefile in cweb file -- Whats the best way? Message-ID: John S. Robinson writes: > The subject line says it all. Since cweb has a tendency to remove tabs > and to insert #line statements, it seems a bit difficult to > specify Makefile definitions after "@(Makefile@>=" directives. > > Do any users have any suggests, or perhaps I should use another tool. > I am usually programming in C++. You can always use @= to insert verbatim text in a code chunk. This is probably a good idea, since CWEB will do strange typesetting things to your makefile stuff. You should also redefine \vb=\. to get rid of the boxes woven around verbatim code. You can also use noweb, nuweb, etc. -- Lee P.S. I've generally refrained from including makefile information in my webs. The chicken & egg problem of ``how do you make the makefile'' bothers me philosophically. Then again, CWEB will always create a new makefile whenever you make the .c (or .cc) file. This could confuse the operating system. I generally tend to think of a makefile as a metalevel in the process, so it doesn't actually belong in the web (or is that just a rationalization?). ------------------------------------------------------------------------ Lee Wittenberg | Halavah is a form of pie, and it has a Computer Science Department | specific gravity of 3.1416 and a specific Kean College of New Jersey | heat of .31416 Union, NJ 07083 | USA | -- D. E. Knuth | "The Potrzebie System of Weights leew@pilot.njin.net | and Measures" (1957) ------------------------------------------------------------------------ ================================================================================ Archive-Date: Mon, 03 Oct 1994 12:10:28 CDT Sender: owner-litprog@SHSU.edu From: trashy@icicle.winternet.com (Barry Schwartz) Reply-To: LitProg@SHSU.edu, trashy@ICICLE.WINTERNET.COM Subject: Re: Makefile in cweb file -- Whats the best way? Date: 3 Oct 1994 16:23:23 GMT Message-ID: <36pb5r$mr9@blackice.winternet.com> To: LitProg@SHSU.EDU In article <1994Sep30.131924.11069@afterlife.ncsc.mil> jsrobin@afterlife.ncsc.mil (John S. Robinson) writes: ] ]The subject line says it all. Since cweb has a tendency to remove tabs ] and to insert #line statements, it seems a bit difficult to ] specify Makefile definitions after "@(Makefile@>=" directives. ] ]Do any users have any suggests, or perhaps I should use another tool. ] I am usually programming in C++. ]-- ]------------------------------------------------------------------------ ]Friends don't let friends do DOS. And friends don't let friends put makefiles in CWEB webs. I think your problem is that you are using a plier where a wrench is needed. If you want to mix languages, use a tool that lets you mix languages. I like noweb. I think CWEB imposes too much composition style, anyway. -- Barry Schwartz at MedGraphics trashy@winternet.com ================================================================================ Archive-Date: Mon, 03 Oct 1994 18:17:04 CDT Sender: owner-litprog@SHSU.edu From: brothers@mdd.comm.mot.com (Joseph Brothers) Reply-To: LitProg@SHSU.edu, brothers@MDD.COMM.MOT.COM Subject: Re: Makefile in cweb file -- Whats the best way? Date: 3 Oct 1994 15:02:33 -0700 Message-ID: <36pv1p$1q2@bb13c.mdd.comm.mot.com> To: LitProg@SHSU.EDU I prefer noweb becuase it mostly stays out of my way. The 2.6c version of noweb knows enough about C to meet my minimum needs, including some form of pretty-printing (via the embedded makefile and \include{}) and cross-referencing. Here's a scrap from my noweb document. It builds the document's Makefile. The Makefile not only weaves the document, it tangles the software source and compiles and installs it too. Note the 'unexpand' command, a handy Unix tool necessary for proper "tabination" of the output. The incp filter is something I built to permit noweb documents to include other noweb documents. \section{MakeFile} <>= Makefile: tsclient.nw notangle -filter incp -RMakefile tsclient.nw | unexpand > Makefile @ -- Joseph L. Brothers brothers@mdd.comm.mot.com uunet!mdisea!brothers "I am speaking solely for my self, not my employer." ================================================================================ Archive-Date: Mon, 03 Oct 1994 19:37:32 CDT Sender: owner-litprog@SHSU.edu From: ceblair@ux1.cso.uiuc.edu (Charles Blair) Reply-To: LitProg@SHSU.edu, ceblair@UX1.CSO.UIUC.EDU Subject: Cross-referencing in cweb Date: 3 Oct 1994 23:01:39 GMT Message-ID: <36q2gj$kmh@vixen.cso.uiuc.edu> To: LitProg@SHSU.EDU Is there a simple way to refer to a later module in the text part of a module. Something like this: @ The lists are sorted in @. @c .... (much later) @ @= ... with cweb supplying the appropriate module number and perhaps expanding an abbreviation for the module name. ================================================================================ Archive-Date: Tue, 04 Oct 1994 08:14:41 CDT Sender: owner-litprog@SHSU.edu From: "Denis B. Roegel" Reply-To: LitProg@SHSU.edu, Denis.Roegel@LORIA.FR Message-ID: <199410041306.OAA00747@pandore.loria.fr> Subject: Re: Cross-referencing in cweb To: LitProg@SHSU.edu, ceblair@ux1.cso.uiuc.edu Date: Tue, 4 Oct 1994 14:06:01 +0100 (MET) CC: roegel@lorraine.loria.fr (Denis B. Roegel) MIME-Version: 1.0 Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: 8bit 'Charles Blair' > > Is there a simple way to refer to a later module in the > text part of a module. > > Something like this: > > @ > The lists are sorted in @. > @c > .... > > (much later) > > @ > @= > ... > > with cweb supplying the appropriate module number and perhaps > expanding an abbreviation for the module name. > Try @ The lists are sorted in |@|. @c .... Denis. ================================================================================ Archive-Date: Tue, 04 Oct 1994 13:58:42 CDT Sender: owner-litprog@SHSU.edu From: cnas30@ccsun.strath.ac.uk (E. St. John-Olcayto) Subject: FWEB Date: 4 Oct 1994 18:46:41 GMT Message-ID: <36s7uh$i2c@rockall.cc.strath.ac.uk> Reply-To: LitProg@SHSU.edu, cnas30@ccsun.strath.ac.uk Keywords: Linux To: LitProg@SHSU.EDU Hi, I'm new to this group. I'm about to embark on a major programming exercise on a 486/Linux platform and I have decided to use an LP tool, FWEB in particular. Is there anybody out there who knows where to get FWEB for Linux or if the source has any problem compiling on a Linux box? All answers appreciated, thanks in advance. --- ------------------------------------------------------------------------------ | Ender St. John-Olcayto | "The concept of a | | Industrial Control Centre | fuzzy state needs | | Department of Electronic and Electrical Engineering | to be clarified" | | University of Strathclyde | | | Scotland | Fuzzy Sets and | | Tel.:+44 41 552 4400 x2666 | Systems | | Fax.:+44 41 553 1232 | | | | Dubois and Prade | | Email : cnas30@ccsun.strath.ac.uk (preferred) | | | or : sender@icu.strath.ac.uk | | ------------------------------------------------------------------------------ ================================================================================ Archive-Date: Tue, 04 Oct 1994 17:23:22 CDT Sender: owner-litprog@SHSU.edu From: tsl1@cornell.edu (Timothy Larkin) Reply-To: LitProg@SHSU.edu, tsl1@CORNELL.EDU Subject: Re: CWEB wishes. mini-index, open, nest-fix, alignment-control Date: 4 Oct 1994 20:51:38 GMT Message-ID: To: LitProg@SHSU.EDU In article <36scmm$26k@telaviv.etak.com>, yotam@etak.com (Yotam Medini) wrote: > * Fix nesting losses. Frequently, after some long 'for' loop header > or some several nested loops, cweave gives up on push-right-indenting > the code. > For example try cweave+tex+xdvi the following: @ Actually, CWeave formats this perfectly well. However, you need to be aware that you can confuse CWeave by failing to keep it informed about the meanings of symbols. I most frequently encounter this myself when I use a Mac ToolBox type that has no definition in my web source. Your example makes the twin error. CWeave thinks that "line" is the line directive, whereas you use it as a variable name. If you include the instruction, @f line x, before @c, to tell CWeave that "line" should be treated as a simple variable, CWeave will format the code correctly. @ > It is obvious that the code above is meant to be aligned for both > the field name and the field comment. Your suggest that the programmer have tab stops to play around with has some merit. However, I prefer to leave all these decisions to CWeave. This is the advantage (and disadvantage) of automatic pretty printing. Cordially, -- tsl1@cornell.edu Timothy Larkin He said that the world was sentient to its core and secret and black beyond men's imagining and that its nature did not reside in what could be seen or not seen. --Cormac McCarthy, "The Crossing" Public key 768/6CC32A85 ================================================================================ Archive-Date: Tue, 04 Oct 1994 17:23:39 CDT Sender: owner-litprog@SHSU.edu From: yotam@etak.com (Yotam Medini) Reply-To: LitProg@SHSU.edu, yotam@ETAK.COM Subject: CWEB wishes. mini-index, open, nest-fix, alignment-control Date: 4 Oct 1994 13:07:50 -0700 Message-ID: <36scmm$26k@telaviv.etak.com> Keywords: CWEB, CWEAVE, MINI-INDEX, ALIGNMENT To: LitProg@SHSU.EDU Let me skip the standard excuses of being a new CWEB baby-user. I strongly appreciate CWEB core ideas, but I believe that CWEB will never gain the wide acceptance it deserves as long as its output is frequently worse than what the typical programmer expects. Here are the features that I wish would be implemented in CWEB. CTANGLE: * Beautify and open the control of the output. This is important when using CWEB to produce exported header files that may be used by non-CWEB/TeX-speaking programmers. CWEAVE: * In DEK's "The Stanford GraphBase" there are wonderful mini-indexes on the odd right-side pages. In page 576 the paragraph titled 'About this book' reveals that these mini-indexes were produced by CTWILL. The source for CTWILL is located in: labrea.stanford.edu:/pub/ctwill Unfortunately, it seems that it is not in a 'production-reliable-status'. Quoting from ctwill.w: \.{CTWILL} was hacked together hastily in June, 1992, to generate pages for Knuth's book about the Stanford GraphBase, and updated even more hastily in March, 1993 to generate final copy for that book. The main idea was to extend \.{CWEAVE} so that ``mini-indexes'' could appear. No time was available to make \.{CTWILL} into a refined or complete system, nor even to fully update the program documentation below. Let us have it as a cweave full-working option! * This is "religious-related". Open control to styles of where to put braces, and when to insert new-lines. * Fix nesting losses. Frequently, after some long 'for' loop header or some several nested loops, cweave gives up on push-right-indenting the code. For example try cweave+tex+xdvi the following: ------------------------------ nest.w ------------------------------ @* WEB-nesting. Try this: @c static int filter_single_non_addressed(BLOCK *pb) { static const char *err_colon_fmt = "colon not found"; int n_rec, n_names, n_single, n_output, n_curr_name /* statistics */; for (n_rec = n_single = n_output = n_names = n_curr_name = li = 0, lp =1; fgets(line[li], sizeof(line[0]), pb->fdump); n_rec++, lp = li, li = 1 - li) { pcolon1[li] = strchr(line[li], ':'); if (pcolon1 == NULL) { error_exit(pb, err_colon_fmt, pb->tmp_fn, n_rec+1, line); } *pcolon1[li] = '\0'; /* trim line for name */ if (strcmp(line[0], line[1])) { /* a new name */ n_names++; n_curr_name = 1; } else { n_curr_name++; } } return(1); } -------------------------------------------------------------------- * Alignment control. Let me quote from X11/Xlib.h: ------------------------------ Xlib.h ------------------------------ typedef struct { XExtData *ext_data; /* hook for extension to hang data */ Font fid; /* Font id for this font */ unsigned direction; /* hint about direction the font is painted */ unsigned min_char_or_byte2;/* first character */ unsigned max_char_or_byte2;/* last character */ unsigned min_byte1; /* first row that exists */ unsigned max_byte1; /* last row that exists */ Bool all_chars_exist;/* flag if all characters have non-zero size*/ unsigned default_char; /* char to print for undefined character */ int n_properties; /* how many properties there are */ XFontProp *properties; /* pointer to array of additional properties*/ XCharStruct min_bounds; /* minimum bounds over all existing char*/ XCharStruct max_bounds; /* maximum bounds over all existing char*/ XCharStruct *per_char; /* first_char to last_char information */ int ascent; /* log. extent above baseline for spacing */ int descent; /* log. descent below baseline for spacing */ } XFontStruct; -------------------------------------------------------------------- It is obvious that the code above is meant to be aligned for both the field name and the field comment. I could think of two approaches for letting the final TeX'ed output to look nicely aligned. + Introduce a new control ('@a') sequence, where the user will be able to define 'tabulator points' on the fly. (@a on a single line by itself will reset). For example: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - typedef struct { @a @a @a XExtData *ext_data; /* hook for extension to hang data */ Font fid; /* Font id for this font */ unsigned min_char_or_byte2; /* first character */ int descent; /* log. descent below baseline for spacing */ @a } AlignedStruct; - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + Make cweave smart, to identify such aligned blocks in the source. Such sensitivity could be controlled by some parameters such as: - How many spaces before a text it takes to make it a candidate for an alignment. - How many consecutive source lines with similar alignment should tell cweave that this is not a coincidence. Thanks for listening->debating->implementing !! yotam (yotam@etak.com, yotam@netcom.com) ================================================================================ Archive-Date: Tue, 04 Oct 1994 21:54:11 CDT Sender: owner-litprog@SHSU.edu From: jsrobin@afterlife.ncsc.mil (John S. Robinson) Reply-To: LitProg@SHSU.edu, jsrobin@AFTERLIFE.NCSC.MIL Subject: Re: FWEB Message-ID: <1994Oct5.001139.23278@afterlife.ncsc.mil> Keywords: Linux Date: Wed, 5 Oct 1994 00:11:39 GMT To: LitProg@SHSU.EDU In article <36s7uh$i2c@rockall.cc.strath.ac.uk>, E. St. John-Olcayto wrote: >Hi, >I'm new to this group. I'm about to embark on a major programming exercise >on a 486/Linux platform and I have decided to use an LP tool, FWEB in >particular. Is there anybody out there who knows where to get FWEB for Linux >or if the source has any problem compiling on a Linux box? > I have have compiled and used FWEB 1.40 in tex mode successfully on a 486/linux platform. It seems it bit buggy in latex mode though. I so far have not had fweave successfully generated a tex file that could be processed by latex. I have had the same problem on a sparc. Hence I don't think the problem is linux related. -- ------------------------------------------------------------------------ Friends don't let friends do DOS. ================================================================================ Archive-Date: Wed, 05 Oct 1994 03:40:24 CDT Sender: owner-litprog@SHSU.edu Date: Wed, 5 Oct 1994 09:39:20 +0100 From: Bernard URBAN Reply-To: LitProg@SHSU.edu, Bernard.URBAN@METEO.FR Message-ID: <199410050839.AA08145@hathor.meteo.fr> To: LitProg@SHSU.edu, jsrobin@AFTERLIFE.NCSC.MIL CC: LitProg@SHSU.EDU Subject: Re: FWEB You write: From: jsrobin@afterlife.ncsc.mil (John S. Robinson) Reply-To: LitProg@SHSU.edu, jsrobin@AFTERLIFE.NCSC.MIL Date: Wed, 5 Oct 1994 00:11:39 GMT In article <36s7uh$i2c@rockall.cc.strath.ac.uk>, E. St. John-Olcayto wrote: >Hi, >I'm new to this group. I'm about to embark on a major programming exercise >on a 486/Linux platform and I have decided to use an LP tool, FWEB in >particular. Is there anybody out there who knows where to get FWEB for Linux >or if the source has any problem compiling on a Linux box? > I have have compiled and used FWEB 1.40 in tex mode successfully on a 486/linux platform. It seems it bit buggy in latex mode though. I so far have not had fweave successfully generated a tex file that could be processed by latex. I have had the same problem on a sparc. Hence I don't think the problem is linux related. I have compiled and run flawlessly Fweb 1.40 with LaTeX 2.09 on both Linux (kernel 1.0.8, gcc 2.4.5, libc 4.4.4) and Sparc (SunOs 4.1, gcc 2.4.5). One thing to remember (and missing from the documentation) if you want to use LaTeX is to change the style file to fwebmacL.sty. Here my .fweb file : +PL +v +wfwebmacL.sty +pLaTeX.options "a4,amssymb" +pLaTeX.style "article" +pindex.tex "#.idx" +pmodules.tex "#.scn" +pcontents.tex "#.cts" +psuffix.Cpp "cc" By the way, you may notice that I use AMS fonts, but I have encountered some difficulties in using AMS styles and french style with Fweb 1.40. For information, here is also the template of the beginning of my Fweb files, which allow for inserting bibliographies. This also should be put in the documentation. \author{(your name and address} \Title{(your title)} \maketitle \renewcommand\botofcontents{\vfill \bibliographystyle{amsplain} \bibliography{(your bibtex files)}} \begin{abstract} (your abstract) \end{abstract} @c++[-W[] B. Urban ================================================================================ Archive-Date: Wed, 05 Oct 1994 05:04:15 CDT Sender: owner-litprog@SHSU.edu Subject: Re: Cross-referencing in cweb Message-ID: From: maavl@cwi.nl (Marc van Leeuwen) Reply-To: LitProg@SHSU.edu, maavl@CWI.NL Date: Wed, 5 Oct 1994 08:56:52 GMT To: LitProg@SHSU.EDU In article <36q2gj$kmh@vixen.cso.uiuc.edu>, ceblair@ux1.cso.uiuc.edu (Charles Blair) writes: |> Is there a simple way to refer to a later module in the |> text part of a module. |> |> Something like this: |> |> @ |> The lists are sorted in @. |> @c |> .... |> |> (much later) |> |> @ |> @= |> ... |> |> with cweb supplying the appropriate module number and perhaps |> expanding an abbreviation for the module name. Yes there is, just write @ The lists are sorted in |@|. @c i.e., put the module name in C mode. Doing this or making forward references to abbreviated module names are no problem in Levy/Knuth CWEB 3.0 or newer. [These things will also be possible in the new release of my implementation of CWEB that was (foolishly) called CWEB 3.x previously, but will henceforth be named CWEBx, but that is besides your point. What may be interesting is that that version allows you to refer to a section number only, by writing @ The lists are sorted in section @#list sorting section@>. @c (much later) @ @:list sorting section@> Here we sort the lists I find this more useful because (1) it also works if the lists are sorted in an unnamed section (one with @c) or (less likely) in the continuation of a module that is defined in multiple sections, (2) it is also possible to refer to pure-documentation sections, (3) the phrase ``The lists are sorted in |@|'' seems to have some redundancy, which can get rather tiring if the module name is really long. A release of CWEBx will be announced soon, but enthusiasts can already get a beta version in ftp.cwi.nl:pub/cweb/beta ] ================================================================================ Archive-Date: Wed, 05 Oct 1994 07:01:19 CDT Sender: owner-litprog@SHSU.edu From: maavl@cwi.nl (Marc van Leeuwen) Reply-To: LitProg@SHSU.edu, maavl@CWI.NL Subject: Re: CWEB wishes. mini-index, open, nest-fix, alignment-control Message-ID: Keywords: CWEB, CWEAVE, MINI-INDEX, ALIGNMENT Date: Wed, 5 Oct 1994 11:25:08 GMT To: LitProg@SHSU.EDU In article <36scmm$26k@telaviv.etak.com>, yotam@etak.com (Yotam Medini) writes: |> I strongly appreciate CWEB core ideas, but I believe that CWEB |> will never gain the wide acceptance it deserves as long as its output is |> frequently worse than what the typical programmer expects. |> |> Here are the features that I wish would be implemented in CWEB. Some of the features you mention are implemented in my implementation CWEBx of CWEB (previously called CWEB 3.x) that is now in beta testing; you can get it from ftp.cwi.nl:/pub/cweb/beta. I find that in this version I can get almost all output to look as I wish if a bit of attention is paid to it; partly this is because I was in a position to adapt the grammar to my wishes, but all the style variation I wanted are implemented as command line options, so you can still get the (ugly:-) style variations that other people seem to prefer just as easily. References to CTANGLE and CWEAVE below are to the programs of CWEBx. |> CTANGLE: |> |> * Beautify and open the control of the output. |> This is important when using CWEB to produce exported header files |> that may be used by non-CWEB/TeX-speaking programmers. CTANGLE has a `-l' switch that will turn off #line directives, preserve spacing and comments from the input, and even tries to construct a proper indentation for inserted uses of modules. |> CWEAVE: |> |> |> * In DEK's "The Stanford GraphBase" there are wonderful mini-indexes |> on the odd right-side pages. In page 576 the paragraph titled |> 'About this book' reveals that these mini-indexes were produced by CTWILL. |> The source for CTWILL is located in: |> labrea.stanford.edu:/pub/ctwill |> Unfortunately, it seems that it is not in a 'production-reliable-status'. Remarkable. I thought the mini-indexes were a kind of private secret that Knuth kept to ensure that some copyright could be attached to the book of which the sources are almost completly public (see the copyright notice that explicitly mentions special indexes). Aparently I was mistaken. It seems promising to try to include this in the standard CWEAVE program, but it will take a bit of work. |> * This is "religious-related". Open control to styles |> of where to put braces, and when to insert new-lines. As mentioned above, this can be done in my CWEAVE. Options +u: unaligned braces (`{' dangling at end of line) as in Levy/Knuth CWEB +w: wide braces (`{' on a line of its own) (default) (`{' aligned with `}' at beginning of a line, but followed (usually) by a statement indented one stop, aligning with the next line +f: force statements on a new line +a: even more so: even if statement follows `if(..)' or a label. +m: do not force declarations in a local block on separate lines |> * Alignment control. [example deleted] |> It is obvious that the code above is meant to be aligned for both |> the field name and the field comment. |> I could think of two approaches for letting the final TeX'ed |> output to look nicely aligned. |> + Introduce a new control ('@a') sequence, where the user will be able |> to define 'tabulator points' on the fly. |> (@a on a single line by itself will reset). For example: |> - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - |> typedef struct { |> @a @a @a |> XExtData *ext_data; /* hook for extension to hang data */ |> Font fid; /* Font id for this font */ |> unsigned min_char_or_byte2; /* first character */ |> int descent; /* log. descent below baseline for spacing */ |> @a |> } AlignedStruct; |> - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Two difficulties: CWEAVE is normally not very aware of the column of the input line it is on (tabs are weird things, and not everybody likes them to be 8 spaces wide), and the output has to be breakable accross lines if they get to wide for the page, which is not easy to achieve in a tabular context. |> + Make cweave smart, to identify such aligned blocks in the source. |> Such sensitivity could be controlled by some parameters such as: |> - How many spaces before a text it takes to make it |> a candidate for an alignment. |> - How many consecutive source lines with similar alignment |> should tell cweave that this is not a coincidence. This is even harder to define or to implement. Care to try? ================================================================================ Archive-Date: Wed, 05 Oct 1994 08:58:41 CDT Sender: owner-litprog@SHSU.edu Date: Wed, 5 Oct 94 9:58:36 EDT From: Lee Wittenberg Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET To: LitProg@shsu.edu, ceblair@ux1.cso.uiuc.edu Subject: Re: Cross-referencing in cweb Message-ID: Charles Blair asks: > Is there a simple way to refer to a later module in the > text part of a module. > > Something like this: > > @ > The lists are sorted in @. > @c > .... > > (much later) > > @ > @= > ... > > with cweb supplying the appropriate module number and perhaps > expanding an abbreviation for the module name. Yes. In CWEB 3.0 (& up), you can say @ The lists are sorted in |@|. @c ... which works just as you would expect. -- Lee ------------------------------------------------------------------------ Lee Wittenberg | Halavah is a form of pie, and it has a Computer Science Department | specific gravity of 3.1416 and a specific Kean College of New Jersey | heat of .31416 Union, NJ 07083 | USA | -- D. E. Knuth | "The Potrzebie System of Weights leew@pilot.njin.net | and Measures" (1957) ------------------------------------------------------------------------ ================================================================================ Archive-Date: Wed, 05 Oct 1994 11:14:27 CDT Sender: owner-litprog@SHSU.edu From: freedom@phantom.com Reply-To: LitProg@SHSU.edu, freedom@PHANTOM.COM Subject: Programmers wanted Date: 5 Oct 1994 11:04:47 -0500 Message-ID: <9410051603.AA21747@mindvox> To: LitProg@SHSU.EDU We are putting together two teams of programmers to develop a custom software application. The work will begin in the next few weeks and will take approximately 6 to 18 weeks depending upon position. Certain positions may involve travel to Europe towards the end of the project. The first team will be building an application for Microsoft Windows. All positions will require proficiency with Visual Basic, certain positions will require proficiency with Visual C/C++. The second team will be building a distributed application over Solaris 2.3. All positions will require proficiency in C/C++, client-server architecture development, and general knowledge of programming in a UNIX environment. All applicants must within commuting distance of Manhattan. Please forward resumes to : freedom@phantom.com ================================================================================ Archive-Date: Wed, 05 Oct 1994 11:14:40 CDT Sender: owner-litprog@SHSU.edu From: trashy@icicle.winternet.com (Barry Schwartz) Reply-To: LitProg@SHSU.edu, trashy@ICICLE.WINTERNET.COM Subject: Re: Cross-referencing in cweb Date: 5 Oct 1994 15:56:51 GMT Message-ID: <36uic3$nue@blackice.winternet.com> To: LitProg@SHSU.EDU In article <36q2gj$kmh@vixen.cso.uiuc.edu> ceblair@ux1.cso.uiuc.edu (Charles Blair) writes: ] Is there a simple way to refer to a later module in the ]text part of a module. Instead of depending on cweb to do all the text processing for you (it can never be powerful enough, and isn't very extensible), you can try using Karl Berry's eplain macros. Then you can set up any sort of cross-links scheme you want, using the \ref mechanism. With eplain, as with LaTeX, you have to do multiple passes over the document to resolve these things. You get a lot of other stuff, besides. For instance, there are macros for drawing commutative diagrams. I haven't drawn too many of those lately, but I was able to adapt eplain to draw pictorials of skip lists, within a CWEB program. -- Barry Schwartz at MedGraphics trashy@winternet.com ================================================================================ Archive-Date: Wed, 05 Oct 1994 11:48:19 CDT Sender: owner-litprog@SHSU.edu From: trashy@icicle.winternet.com (Barry Schwartz) Reply-To: LitProg@SHSU.edu, trashy@ICICLE.WINTERNET.COM Subject: Re: CWEB wishes. mini-index, open, nest-fix, alignment-control Date: 5 Oct 1994 16:32:31 GMT Message-ID: <36ukev$o96@blackice.winternet.com> To: LitProg@SHSU.EDU In article <36scmm$26k@telaviv.etak.com> yotam@etak.com (Yotam Medini) writes: ]Let me skip the standard excuses of being a new CWEB baby-user. ] ]I strongly appreciate CWEB core ideas, but I believe that CWEB ]will never gain the wide acceptance it deserves as long as its output is ]frequently worse than what the typical programmer expects. ] ]Here are the features that I wish would be implemented in CWEB. With CWEB, there'll always be something someone wants and can't have, because it tries to do too much in its kernel. Witness the recent complaint in this newsgroup from someone trying to put makefiles in the CWEB sources. CWEAVE tries to be the perfect C programming tool right out of the box, and so comes up completely unable to handle makefiles. And if you are going to get all the C formatting choices that you want, it will all have to be hacked into CWEAVE, and then every CWEB user will have to shlep it around whether he or she uses it or not. And then CWEB will be a moving target, like the shrink-wrap we've all come to know and hate. Furthermore, CWEB will never take off because C is in decline. I believe CWEB is too difficult to use with C++. And what good's this language dependence, anyway? I'd rather write a program in Icon than in C, if I can get away with it. Why should I have to use C to be literate? Why can't I make my Perl scripts and stuff-written-in-the- special-purpose-language-developed-just-for-this-project literate? I think that, if there is a future in literate programming (and I think there is), that it looks more like noweb than CWEB. Noweb takes advantage of the development environment, using it to make weaving and tangling flexible and extensible. You lose the near-complete platform independence of CWEB, but noweb is so simple that it can be ported to a new operating system in a short while, if the OS is powerful enough and supports C (and C++, if you use Lee Wittenberg's MS-DOS port of noweb as your base) and Icon (which is portable and free). And noweb is extremely simple to use. What else do you lose? Well, there's no built-in prettyprinting, though it can be added as a filter if you want to go to the trouble. Prettyprinters already exist for a few languages (C not included). But program text in monospaced font is adequate, I have found, and the human-language writing comes out much better than with CWEB, because I can use a standard article format. (I haven't tried writing a literate program as a letter, but I have the idea in the back of my mind.) Automatic indexing is not so fancy as with CWEB, but tools to handle that are improving--as I said, noweb is extensible. And you can manually index any language at all. If you want, you can use standard LaTeX indexing tools to get a traditional index, as well. You can add a bibliography, or anything else like that. I've been able to do a bibliography with CWEB, by using eplain macros, but it's always an add-on with CWEB. With noweb, it's standard LaTeX. And you don't have to use LaTeX. You can generate output for plain TeX, or HTML, or LaTeX2HTML. Or anything else, if you care to write the back-end (for which you don't have to rewrite all the other components). Did I mention that noweb is almost trivial to use? -- Barry Schwartz at MedGraphics trashy@winternet.com ================================================================================ Archive-Date: Wed, 05 Oct 1994 13:27:40 CDT Sender: owner-litprog@SHSU.edu From: dxb37@po.CWRU.Edu (Dean Boland) Reply-To: LitProg@SHSU.edu, dxb37@PO.CWRU.EDU Subject: New to Programming.... Any help would be cool! Date: 5 Oct 1994 17:46:13 GMT Message-ID: <36uop5$6ig@usenet.INS.CWRU.Edu> To: LitProg@SHSU.EDU I have a book on programming in basic for Dos. But, I have also heard that programming in C would be better for utilities etc. which is what I want to do. Do I need something other than a IBM PC to being programming in C??? -- Dean. ================================================================================ Archive-Date: Thu, 06 Oct 1994 01:39:19 CDT Sender: owner-litprog@SHSU.edu Date: Wednesday, 5 October 1994 11:31pm PT From: Mail.Away@ncal.kaiperm.org Reply-To: LitProg@SHSU.edu, Mail.Away@NCAL.KAIPERM.ORG Subject: HS Re: FWEB To: LitProg@SHSU.edu, Bernard.URBAN@meteo.fr The following request was returned because the subject did not name a valid file. You write: From: jsrobin@afterlife.ncsc.mil (John S. Robinson) Reply-To: LitProg@SHSU.edu, jsrobin@AFTERLIFE.NCSC.MIL Date: Wed, 5 Oct 1994 00:11:39 GMT In article <36s7uh$i2c@rockall.cc.strath.ac.uk>, E. St. John-Olcayto wrote: >Hi, >I'm new to this group. I'm about to embark on a major programming e >on a 486/Linux platform and I have decided to use an LP tool, FWEB i >particular. Is there anybody out there who knows where to get FWEB Linux >or if the source has any problem compiling on a Linux box? > I have have compiled and used FWEB 1.40 in tex mode successfully on a 486/linux platform. It seems it bit buggy in latex mode though. I so far have not had fwe successfully generated a tex file that could be processed by latex. I have had the same problem on a sparc. Hence I don't think the problem is linux related. I have compiled and run flawlessly Fweb 1.40 with LaTeX 2.09 on both Linux (kernel 1.0.8, gcc 2.4.5, libc 4.4.4) and Sparc (SunOs 4.1, gcc 2.4.5). One thing to remember (and missing from the documentation) if you want to use LaTeX is to change the style file to fwebmacL.sty. Here my .fweb file : +PL +v +wfwebmacL.sty +pLaTeX.options "a4,amssymb" +pLaTeX.style "article" +pindex.tex "#.idx" +pmodules.tex "#.scn" +pcontents.tex "#.cts" +psuffix.Cpp "cc" By the way, you may notice that I use AMS fonts, but I have encountered some difficulties in using AMS styles and french style with Fweb 1.40. For information, here is also the template of the beginning of my Fweb files, which allow for inserting bibliographies. This also should be put in the documentation. \author{(your name and address} \Title{(your title)} \maketitle \renewcommand\botofcontents{\vfill \bibliographystyle{amsplain} \bibliography{(your bibtex files)}} \begin{abstract} (your abstract) \end{abstract} @c++[-W[] B. Urban ================================================================================ Archive-Date: Thu, 06 Oct 1994 01:39:28 CDT Sender: owner-litprog@SHSU.edu Date: Wednesday, 5 October 1994 11:31pm PT From: Mail.Away@ncal.kaiperm.org Reply-To: LitProg@SHSU.edu, Mail.Away@NCAL.KAIPERM.ORG Subject: HS Re: FWEB To: LitProg@SHSU.edu, jsrobin@afterlife.ncsc.mil The following request was returned because the subject did not name a valid file. In article <36s7uh$i2c@rockall.cc.strath.ac.uk>, E. St. John-Olcayto wrote: >Hi, >I'm new to this group. I'm about to embark on a major programming exer >on a 486/Linux platform and I have decided to use an LP tool, FWEB in >particular. Is there anybody out there who knows where to get FWEB for >or if the source has any problem compiling on a Linux box? > I have have compiled and used FWEB 1.40 in tex mode successfully on a 486/linux platform. It seems it bit buggy in latex mode though. I so far have not had fweave successfully generated a tex file that could be processed by latex. I have had the same problem on a sparc. Hence I don't think the problem is linux related. -- ------------------------------------------------------------------------ Friends don't let friends do DOS. ================================================================================ Archive-Date: Thu, 06 Oct 1994 01:40:23 CDT Sender: owner-litprog@SHSU.edu Date: Wednesday, 5 October 1994 11:30pm PT From: Mail.Away@ncal.kaiperm.org Reply-To: LitProg@SHSU.edu, Mail.Away@NCAL.KAIPERM.ORG Subject: HS Re: CWEB wishes. mini-index, ope To: LitProg@SHSU.edu, maavl@cwi.nl The following request was returned because the subject did not name a valid file. In article <36scmm$26k@telaviv.etak.com>, yotam@etak.com (Yotam Medini) writes: |> I strongly appreciate CWEB core ideas, but I believe that CWEB |> will never gain the wide acceptance it deserves as long as its output |> frequently worse than what the typical programmer expects. |> |> Here are the features that I wish would be implemented in CWEB. Some of the features you mention are implemented in my implementation CW of CWEB (previously called CWEB 3.x) that is now in beta testing; you ca get it from ftp.cwi.nl:/pub/cweb/beta. I find that in this version I can almost all output to look as I wish if a bit of attention is paid to it; partly this is because I was in a position to adapt the grammar to my wishes, but all the style variation I wanted are implemented as command options, so you can still get the (ugly:-) style variations that other people seem to prefer just as easily. References to CTANGLE and CWEAVE b are to the programs of CWEBx. |> CTANGLE: |> |> * Beautify and open the control of the output. |> This is important when using CWEB to produce exported header file |> that may be used by non-CWEB/TeX-speaking programmers. CTANGLE has a `-l' switch that will turn off #line directives, preserve spacing and comments from the input, and even tries to construct a prope indentation for inserted uses of modules. |> CWEAVE: |> |> |> * In DEK's "The Stanford GraphBase" there are wonderful mini-indexe |> on the odd right-side pages. In page 576 the paragraph titled |> 'About this book' reveals that these mini-indexes were produced b CTWILL. |> The source for CTWILL is located in: |> labrea.stanford.edu:/pub/ctwill |> Unfortunately, it seems that it is not in a 'production-reliable- Remarkable. I thought the mini-indexes were a kind of private secret tha Knuth kept to ensure that some copyright could be attached to the book o which the sources are almost completly public (see the copyright notice explicitly mentions special indexes). Aparently I was mistaken. It seems promising to try to include this in the standard CWEAVE program but it will take a bit of work. |> * This is "religious-related". Open control to styles |> of where to put braces, and when to insert new-lines. As mentioned above, this can be done in my CWEAVE. Options +u: unaligned braces (`{' dangling at end of line) as in Levy/Knuth CWEB +w: wide braces (`{' on a line of its own) (default) (`{' aligned with `}' at beginning of a line, but followed (usually) by a statement indented one stop, aligning with the next l +f: force statements on a new line +a: even more so: even if statement follows `if(..)' or a label. +m: do not force declarations in a local block on separate lines |> * Alignment control. [example deleted] |> It is obvious that the code above is meant to be aligned for both |> the field name and the field comment. |> I could think of two approaches for letting the final TeX'ed |> output to look nicely aligned. |> + Introduce a new control ('@a') sequence, where the user will be |> to define 'tabulator points' on the fly. |> (@a on a single line by itself will reset). For example: |> - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - |> typedef struct { |> @a @a @a |> XExtData *ext_data; /* hook for extension to hang data */ |> Font fid; /* Font id for this font */ |> unsigned min_char_or_byte2; /* first character */ |> int descent; /* log. descent below baseline for spacin |> @a |> } AlignedStruct; |> - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Two difficulties: CWEAVE is normally not very aware of the column of the input line it is on (tabs are weird things, and not everybody likes them be 8 spaces wide), and the output has to be breakable accross lines if t get to wide for the page, which is not easy to achieve in a tabular cont |> + Make cweave smart, to identify such aligned blocks in the sourc |> Such sensitivity could be controlled by some parameters such as |> - How many spaces before a text it takes to make it |> a candidate for an alignment. |> - How many consecutive source lines with similar alignment |> should tell cweave that this is not a coincidence. This is even harder to define or to implement. Care to try? ================================================================================ Archive-Date: Thu, 06 Oct 1994 03:02:05 CDT Sender: owner-litprog@SHSU.edu Date: Thu, 06 Oct 1994 08:39:00 -0700 (PDT) From: "Stephen Boyan (510) 926-3291/fax 926-3604" Reply-To: LitProg@SHSU.edu, BOYANST@NCAL.KAIPERM.ORG Subject: RE: HS Re: FWEB To: owner-litprog CC: LitProg , "Bernard.URBAN" I wish to apologize for an error that led to some garbage mail being sent to the LITPROG mail server. While testing a mail server I'm developing, I accidently returned some letters from my inbasket to the LITPROG and some contributors. I have modified my programs to prevent this from reoccurring, but I should have been more careful in the first place. The junk mail has subject that start "HS ". ================================================================================ Archive-Date: Thu, 06 Oct 1994 03:14:00 CDT Sender: owner-litprog@SHSU.edu Date: Thu, 06 Oct 1994 08:58:00 -0700 (PDT) From: "Stephen Boyan (510) 926-3291/fax 926-3604" Reply-To: LitProg@SHSU.edu, BOYANST@NCAL.KAIPERM.ORG Subject: Apologies To: litprog@shsu.edu I wish to apologize for an error that led to some garbage mail being sent to the LITPROG mail server. While testing a mail server I'm developing, I accidently returned some letters from my inbasket to the LITPROG and some contributors. I have modified my programs to prevent this from reoccurring, but I should have been more careful in the first place. The junk mail has subject that start "HS ". ================================================================================ Archive-Date: Thu, 06 Oct 1994 07:50:47 CDT Sender: owner-litprog@SHSU.edu From: partingr@p4.cs.man.ac.uk (Robert Partington) Reply-To: LitProg@SHSU.edu, partingr@P4.CS.MAN.AC.UK Subject: NOWEB vs CWEB (was Re: CWEB wishes...) Date: 6 Oct 1994 12:43:07 GMT Message-ID: <370rcr$8vo@m1.cs.man.ac.uk> To: LitProg@SHSU.EDU trashy@icicle.winternet.com (Barry Schwartz) writes: >And you don't have to use LaTeX. You can generate output for plain >TeX, or HTML, or LaTeX2HTML. Or anything else, if you care to write >the back-end (for which you don't have to rewrite all the other >components). Now's a good time to point out my cross-referencer for noweb which works with plain TeX. It's lovely, it's free and it works fine. Get it via email (partingr@cs.man.ac.uk) or WWW (from next week) at http://www.cs.man.ac.uk/~partingr/noweb.html. I also have a parser that identifies variables in perl programs and creates an index for noweb to use. >Did I mention that noweb is almost trivial to use? If I had a C parser and pretty printer, I'd use noweb in preference to CWEB. Rob Partington -- Robert Partington partingr@cs.man.ac.uk Computer Science, 3rd year 25MHz ARM3,80MB HD,4MB A5000 running RO3.11 - but no Settlers or Emacs! 7MHz 68000,40MB HD,7MB A2000 running WB2.1 - Settlers *and* Emacs. Joy. "Hi, my name's Rob - and I'm an emacholic." ================================================================================ Archive-Date: Thu, 06 Oct 1994 17:19:30 CDT Sender: owner-litprog@SHSU.edu From: kaufmanr@pipeline.com (Robert Kaufman) Reply-To: LitProg@SHSU.edu, kaufmanr@PIPELINE.COM Subject: Re: New to Programming.... Any help would be cool! Date: 6 Oct 1994 18:04:40 -0400 Message-ID: <371s9o$q6v@pipe4.pipeline.com> To: LitProg@SHSU.EDU dxb37@po.CWRU.Edu (Dean Boland) wrote: >I have a book on programming in basic for Dos. But, I >have also heard that programming in C would be better >for utilities etc. which is what I want to do. Do I >need something other than a IBM PC to being >programming in C??? One year ago, I would definately said go and learn C. Better yet, C++. Today, it really depends on which environment you want to learn to program for. Do you *really* want to learn how to write programs for the MS-DOS operating system? Not much glory there, and few emerging emmployment op's. If you *do* want to program in MS-DOS, I'd invest the additional time to learn C++, an object-oriented superset of C. GWBASIC and friends are extremely non-portable and don't enforce good programming practice. If, however, you want to learn to program for MS-Windows, I would suggest getting a copy of Visual BASIC 3.00. It's fairly hot stuff, easy to use, and will reward you with working Windows programs the first day you use it. ================================================================================ Archive-Date: Thu, 06 Oct 1994 20:27:30 CDT Sender: owner-litprog@SHSU.edu From: preston@Tera.COM (Preston Briggs) Reply-To: LitProg@SHSU.edu, preston@TERA.COM Subject: Re: CWEB wishes. mini-index, open, nest-fix, alignment-control Date: 6 Oct 1994 09:05:29 -0700 Message-ID: <371789$6dh@sparrow.tera.com> Keywords: CWEB, CWEAVE, MINI-INDEX, ALIGNMENT To: LitProg@SHSU.EDU In article <36scmm$26k@telaviv.etak.com> yotam@etak.com (Yotam Medini) writes: >Here are the features that I wish would be implemented in CWEB. "If you want something done right, ..." That is, nobody's going to do these things for you. However, if you're willing to explore a bit, other people have come up with some alternatives to CWEB. > * Beautify and open the control of the output. [of tangle] > * In DEK's "The Stanford GraphBase" there are wonderful mini-indexes > * This is "religious-related". Open control to styles > of where to put braces, and when to insert new-lines. > > * Fix nesting losses. > + Introduce a new control ('@a') sequence, where the user will be able > to define 'tabulator points' on the fly. > + Make cweave smart, to identify such aligned blocks in the source. Check out noweb, which solves all your problems and more, or nuweb which gets everyhting but the mini-indices (because I could never get them to look pretty enough). Of course, you may not like the "solutions" in some cases! A lot of this is a matter of personal taste, experimentation, and compromise. Preston Briggs ================================================================================ Archive-Date: Thu, 06 Oct 1994 21:27:33 CDT Sender: owner-litprog@SHSU.edu From: kientzle@netcom.com Reply-To: LitProg@SHSU.edu, kientzle@NETCOM.COM Subject: Re: CWEB wishes. mini-index, open, nest-fix, alignment-control Message-ID: Keywords: CWEB, CWEAVE, LATEX Date: Thu, 6 Oct 1994 18:26:59 GMT To: LitProg@SHSU.EDU In article , Marc van Leeuwen wrote: >Some of the features you mention are implemented in my implementation CWEBx >of CWEB (previously called CWEB 3.x) that is now in beta testing... In merging CWEAVE output into LaTeX documents, I've run across one other fairly major stumbling block, which is that CWEAVE inserts _visual_ formatting rather than _logical_ formatting. In the work I'm doing, it would be very nice to have identifier definitions marked-up differently from indentifier uses, so that identifier definitions could be automatically indexed by LaTeX, for example. I've looked through CWEAVE, and this looks doable, but I've not yet tried to modify CWEAVE in this manner. This sort of logical markup would allow the use of standard LaTeX packages to compile multiple indices (e.g., an identifier index at the end of each section, yet all function definitions are also indexed at the end of the book), and other sorts of cross-referencing tricks. If you add this sort of facility to CWEBx, I'm definitely interested. - Tim P.S. I've heard a lot about NOWEB, which sounds like it could be much more appropriate for certain purposes. However, I'm using CWEB to write chapters for books, and really appreciate the pretty-printing and automatic indexing and cross-referencing. ================================================================================ Archive-Date: Fri, 07 Oct 1994 07:25:42 CDT Sender: owner-litprog@SHSU.edu From: maavl@cwi.nl (Marc van Leeuwen) Reply-To: LitProg@SHSU.edu, maavl@CWI.NL Subject: Re: CWEB wishes. mini-index, open, nest-fix, alignment-control Message-ID: Keywords: CWEB, CWEAVE, LATEX Date: Fri, 7 Oct 1994 12:18:12 GMT To: LitProg@SHSU.EDU In article , kientzle@netcom.com writes: |> In merging CWEAVE output into LaTeX documents, I've run across one |> other fairly major stumbling block, which is that CWEAVE inserts |> _visual_ formatting rather than _logical_ formatting. In the work I'm |> doing, it would be very nice to have identifier definitions marked-up |> differently from identifier uses, so that identifier definitions |> could be automatically indexed by LaTeX, for example. I've looked |> through CWEAVE, and this looks doable, but I've not yet tried to |> modify CWEAVE in this manner. This sort of logical markup would allow |> the use of standard LaTeX packages to compile multiple indices (e.g., |> an identifier index at the end of each section, yet all function |> definitions are also indexed at the end of the book), and other sorts |> of cross-referencing tricks. I sympathise with your wishes, but I don't quite understand your first sentence. Of course CWEAVE does visual formatting, at least for the part that cannot be left to be visually formatted by TeX: it issues forced line breaks, explicit changes of indentation level etc. The logical markup is really contained in the source document, and not (fully) in the intermediate file produced by CWEAVE. However CWEAVE does not do complete visual formatting: for instance many symbols like operators are produced as macros, so that you can easily change their appearance by overriding the default definitions, and breaking of long lines is also left to TeX's line breaking algorithm. However, I think this is not really what bothers you. You want CWEAVE to export some of the information about the program that it has access to while processing, although it is not represented explicitly in the input: whether a certain occurrence of an identifier is defining or using. This is analogous to other cases where CWEAVE does make such information explicit, for instance it marks unary and binary uses of operators differently, making the output from |**p| different from $**p$ (where TeX would make the second asterisk a binary operator). And you are right, definitions and uses of identifiers generally trigger different syntax rules, so that CWEAVE could easily make the distinction; in fact it does, but currently this only influences the underlining in the index[*]. To make the change you wish one would have to change the internal coding for identifiers, which currently allows only two attributes---for normal identifiers and reserved words---so as to allow one or two more distinguished variants (defining identifiers and maybe defining reserved words (such as typedef symbols)), which could be altered by |make_underlined| and could determine which macro to use upon output. You have to be careful not to exceed the sixteen bits used to represent identifiers currently, but apart from this it would not be a very difficult change to make. If you want to distinguish really many uses of identifiers (function definitions, local variables, macros, ...) you may want to change the internal coding of identifiers in a more fundamental way. |> If you add this sort of facility to CWEBx, I'm definitely |> interested. Well, I'm not planning to do this on the short term, particularly because within the framework for which CWEB is intended (namely for producing literate presentations of program sources in a fairly standardised format, rather than producing more or less arbitrary documents that happen to contain pieces of program code), it is not quite clear which purpose it would serve, and therefore exactly which kinds of information should be exported. But anybody is invited to make the changes of his liking; CWEBx was (re)written to be more easily understandable and less rigid than CWEB (even though I think it could still bear some improvement in this respect). Marc van Leeuwen CWI, Amsterdam [*] Note however that the logic is not infallible, due to a combination of the brain-damaged syntax of C/C++ for declarations and the weird grammar used by CWEAVE, making that in char *p; char (*q); long (*f) (void); unsigned short (*g)(void); const int *(*h)(void); char *(* volatile *k)(void); the identifiers |p|, |short|, |h|, and |volatile| are considered to be defining, and none from the second and third lines; here at least CWEBx does a more decent job, tripping only over the final case). ================================================================================ Archive-Date: Fri, 07 Oct 1994 09:23:04 CDT Sender: owner-litprog@SHSU.edu From: cnas30@ccsun.strath.ac.uk (E. St. John-Olcayto) Subject: FWEB1.30 Date: 7 Oct 1994 14:01:52 GMT Message-ID: <373kcg$opc@rockall.cc.strath.ac.uk> Reply-To: LitProg@SHSU.edu, cnas30@ccsun.strath.ac.uk Keywords: Latex To: LitProg@SHSU.EDU Hi, I just obtained FWEB v1.30 and compiled it on one of our Sparcs without any problem. However, I can't get the examples to produce LaTeX output (fweave -PL Newton.web for example). Has anybody had any luck in producing Latex output? Thanks, Ender --- ------------------------------------------------------------------------------ | Ender St. John-Olcayto | "The concept of a | | Industrial Control Centre | fuzzy state needs | | Department of Electronic and Electrical Engineering | to be clarified" | | University of Strathclyde | | | Scotland | Fuzzy Sets and | | Tel.:+44 41 552 4400 x2666 | Systems | | Fax.:+44 41 553 1232 | | | | Dubois and Prade | | Email : cnas30@ccsun.strath.ac.uk (preferred) | | | or : sender@icu.strath.ac.uk | | ------------------------------------------------------------------------------ ================================================================================ Archive-Date: Fri, 07 Oct 1994 10:53:48 CDT Sender: owner-litprog@SHSU.edu Date: Fri, 7 Oct 1994 16:52:35 +0100 From: Bernard URBAN Reply-To: LitProg@SHSU.edu, Bernard.URBAN@METEO.FR Message-ID: <199410071552.AA09611@hathor.meteo.fr> To: LitProg@SHSU.edu, cnas30@ccsun.strath.ac.uk CC: LitProg@SHSU.EDU Subject: Re: FWEB1.30 You write: Sender: owner-litprog@SHSU.edu From: cnas30@ccsun.strath.ac.uk (E. St. John-Olcayto) Hi, I just obtained FWEB v1.30 and compiled it on one of our Sparcs without any problem. However, I can't get the examples to produce LaTeX output (fweave -PL Newton.web for example). Has anybody had any luck in producing Latex output? If I remember well (I now use FWEB 1.40), you must also use the style file fwebmacL.sty instead of fwebmac.sty to use LaTeX. B. Urban ================================================================================ Archive-Date: Fri, 07 Oct 1994 15:49:19 CDT Sender: owner-litprog@SHSU.edu Subject: how to convert TTF ---> TEX font ? Message-ID: <1994Oct7.155835.22092@wisipc.weizmann.ac.il> From: iliak@vered.weizmann.ac.il (Kuznetsov Ilia) Reply-To: LitProg@SHSU.edu, iliak@VERED.WEIZMANN.AC.IL Date: Fri, 7 Oct 1994 15:58:35 GMT To: LitProg@SHSU.EDU Does anybody know is it possible to convert TTF ( True Type Font ) to TEX fonts ? And if it is, how to do it ? ================================================================================ Archive-Date: Fri, 07 Oct 1994 16:05:06 CDT Sender: owner-litprog@SHSU.edu From: norman@flaubert.bellcore.com (Norman Ramsey) Reply-To: LitProg@SHSU.edu, norman@FLAUBERT.BELLCORE.COM Subject: Re: CWEB wishes. mini-index, open, nest-fix, alignment-control Date: 7 Oct 1994 19:13:17 GMT Message-ID: <3746kd$ovk@lowell.bellcore.com> Keywords: CWEB, CWEAVE, LATEX CC: kientzle@netcom.com To: LitProg@SHSU.EDU In article , wrote: >P.S. I've heard a lot about NOWEB, which sounds like it could be much >more appropriate for certain purposes. However, I'm using CWEB to >write chapters for books, and really appreciate the pretty-printing >and automatic indexing and cross-referencing. noweb does automatic indexing and cross-referencing for some languages, including C, Icon, TeX, and Standard ML. Some people have made it prettyprint other language, like Icon and Object-Oriented Turing. I haven't been overwhelmed by the results, but then I'm notoriously difficult to convince of the value of prettyprinting. Norman ================================================================================ Archive-Date: Sat, 08 Oct 1994 07:01:19 CDT Sender: owner-litprog@SHSU.edu From: wqdbt@ttacs.ttu.edu (David B. Thompson) Reply-To: LitProg@SHSU.edu, wqdbt@TTACS.TTU.EDU Subject: Re: FWEB Date: Fri, 7 Oct 1994 13:37:34 Message-ID: Keywords: Linux To: LitProg@SHSU.EDU In article <1994Oct5.001139.23278@afterlife.ncsc.mil> jsrobin@afterlife.ncsc.mil (John S. Robinson) writes: >I have have compiled and used FWEB 1.40 in tex mode successfully on a > 486/linux platform. Would you be willing to make this generally available? >It seems it bit buggy in latex mode though. I so far have not had fweave > successfully generated a tex file that could be processed by > latex. If I correctly recall (always dangerous), 1.40 may be a beta release. I think John made some serious changes from the earlier release, hence bugs are quite possible. Did you try 1.36 (is the previous release)? (I guess I need to read my own FAQ! ;-) >I have had the same problem on a sparc. Hence I don't think the > problem is linux related. What about the previous release here? >Friends don't let friends do DOS. Hey! I resemble that remark! :-b -=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: Sat, 08 Oct 1994 16:08:08 CDT Sender: owner-litprog@SHSU.edu From: trashy@icicle.winternet.com (Barry Schwartz) Reply-To: LitProg@SHSU.edu, trashy@ICICLE.WINTERNET.COM Subject: Re: CWEB wishes. mini-index, open, nest-fix, alignment-control Date: 8 Oct 1994 20:46:04 GMT Message-ID: <3770ec$h9a@blackice.winternet.com> To: LitProg@SHSU.EDU In article <3746kd$ovk@lowell.bellcore.com> norman@flaubert.bellcore.com (Norman Ramsey) writes: ]noweb does automatic indexing and cross-referencing for some ]languages, including C, Icon, TeX, and Standard ML. Some people have ]made it prettyprint other language, like Icon and Object-Oriented ]Turing. I haven't been overwhelmed by the results, but then I'm ]notoriously difficult to convince of the value of prettyprinting. I used to think that prettyprinting was the cats meow, but after becoming a bit accustomed to noweb I find that a CWEB printout looks somewhat like gibberish. I think the problem here is not so much that prettyprinting is inherently bad as that many languages don't benefit from it so much. Algol and Pascal, I believe, benefit quite a bit from appropriate prettyprinting. These are languages where you write out a lot of whole words: "begin", "end", "do", "then".... You get the idea. Languages like C and Icon depend a lot on symbolic notation. For the large part, all CWEB does is replace one set of symbols with another that some people happen to prefer. But, still, CWEB puts reserved words and defining words in boldface and identifiers in italics; what of that? In Pascal, doing that helps mark out the form of a construct. In C, on the other hand, the constructs are delimited by things like parentheses and braces, and so putting things in different typefaces doesn't help that much. OK, CWEB indentifies, but you don't need weave to do that; Emacs can do that for you, or you can do it yourself, and the web source will benefit from it. The main thing that I might want from noweb but don't get is typesetting of comments, and I can live without that because I don't need a great many comments. -- Barry Schwartz at MedGraphics trashy@winternet.com ================================================================================ Archive-Date: Mon, 10 Oct 1994 04:46:43 CDT Sender: owner-litprog@SHSU.edu Date: Mon, 10 Oct 1994 10:47:45 +0100 From: jmu@ccr.jussieu.fr (Johannes MULLER) Reply-To: LitProg@SHSU.edu, jmu@CCR.JUSSIEU.FR Message-ID: <199410100947.KAA44963@moka.ccr.jussieu.fr> To: LitProg@SHSU.edu Subject: Re: FWEB on Linux I compiled FWEB without any changes on my Linux box (486DX33, Kernel 1.0, gcc-2.5.8). ftangle as well as fweave compiled without complaint (I think I took the UNIX standard options). ftangle works without problems and produces the expected results; fweave dumps core, somewhere when reading/writing one of the index files. I didn't have the time to fix that, all the more that I print most of my stuff in my lab, where FWEB works fine. But if somebody figures out what's wrong with FWEB (1.30a btw), I'd be interested in knowing. Bye, Johannes jmu@ccr.jussieu.fr ================================================================================ Archive-Date: Mon, 10 Oct 1994 11:32:33 CDT Sender: owner-litprog@SHSU.edu From: matth@cogsci.edinburgh.ac.uk Reply-To: LitProg@SHSU.edu, matth@COGSCI.EDINBURGH.AC.UK Date: Mon, 10 Oct 94 16:39:43 BST Message-ID: <2808.9410101539@galloway.cogsci.ed.ac.uk> To: LitProg@SHSU.edu SIGNOFF LitProg ================================================================================ Archive-Date: Mon, 10 Oct 1994 18:49:36 CDT Sender: owner-litprog@SHSU.edu From: jsrobin@afterlife.ncsc.mil (John S. Robinson) Reply-To: LitProg@SHSU.edu, jsrobin@AFTERLIFE.NCSC.MIL Subject: Re: FWEB Message-ID: <1994Oct10.233933.17827@afterlife.ncsc.mil> Keywords: Linux Date: Mon, 10 Oct 1994 23:39:33 GMT To: LitProg@SHSU.EDU I received a partial solution to my problem of using LaTeX mode in fweb by e-mail . This solution, described below, still yields the following errors: fweave testfile.web This is FWEAVE [UNIX version 1.40 (October 30, 1993)]. Reading /user/jsrobin/fweb.sty... (No testfile.aux file.) Reading testfile.web... *1 *22 Writing testfile.tex... *1 *22 Writing testfile.idx...testfile.scn... Done. CPU = 0.3 sec.; REAL = 0.4 sec. CPU/REAL = 71.7%. [FWEAVE: No errors were found.] //ValueAssignment/fweb 4097 > latex testfile.tex This is TeX, Version 3.1415 (C version 6.0) (testfile.tex LaTeX2e <1993/12/24> PRELIMINARY TEST RELEASE (/usr/TeX/lib/texmf/tex/inputs/fwebmacL.sty LaTeX error. See LaTeX manual for explanation. Type H for immediate help. ! The font family command \rm is not defined.. \@latexerr ...rcontextlines \m@ne \errmessage {#1} \endgroup l.43 ^^I\fontsize{10}{12pt}\rm % The standard font for bulk of document. ? The solution provider stated the following: I have compiled and run flawlessly Fweb 1.40 with LaTeX 2.09 on both Linux (kernel 1.0.8, gcc 2.4.5, libc 4.4.4) and Sparc (SunOs 4.1, gcc 2.4.5). One thing to remember (and missing from the documentation) if you want to use LaTeX is to change the style file to fwebmacL.sty. Here my .fweb file : +PL +v +wfwebmacL.sty +pLaTeX.options "a4,amssymb" +pLaTeX.style "article" +pindex.tex "#.idx" +pmodules.tex "#.scn" +pcontents.tex "#.cts" +psuffix.Cpp "cc" By the way, you may notice that I use AMS fonts, but I have encountered some difficulties in using AMS styles and french style with Fweb 1.40. For information, here is also the template of the beginning of my Fweb files, which allow for inserting bibliographies. This also should be put in the documentation. \author{(your name and address} \Title{(your title)} \maketitle \renewcommand\botofcontents{\vfill \bibliographystyle{amsplain} \bibliography{(your bibtex files)}} \begin{abstract} (your abstract) \end{abstract} @c++[-W[] B. Urban I have compiled and run flawlessly Fweb 1.40 with LaTeX 2.09 on both Linux (kernel 1.0.8, gcc 2.4.5, libc 4.4.4) and Sparc (SunOs 4.1, gcc 2.4.5). One thing to remember (and missing from the documentation) if you want to use LaTeX is to change the style file to fwebmacL.sty. Here my .fweb file : +PL +v +wfwebmacL.sty +pLaTeX.options "a4,amssymb" +pLaTeX.style "article" +pindex.tex "#.idx" +pmodules.tex "#.scn" +pcontents.tex "#.cts" +psuffix.Cpp "cc" By the way, you may notice that I use AMS fonts, but I have encountered some difficulties in using AMS styles and french style with Fweb 1.40. For information, here is also the template of the beginning of my Fweb files, which allow for inserting bibliographies. This also should be put in the documentation. \author{(your name and address} \Title{(your title)} \maketitle \renewcommand\botofcontents{\vfill \bibliographystyle{amsplain} \bibliography{(your bibtex files)}} \begin{abstract} (your abstract) \end{abstract} @c++[-W[] B. Urban -- ------------------------------------------------------------------------ Friends don't let friends do DOS. ================================================================================ Archive-Date: Tue, 11 Oct 1994 02:47:12 CDT Sender: owner-litprog@SHSU.edu From: knobi@architektur.uni-kassel.de (Frank Knobloch) Subject: modem-programming Date: 10 Oct 1994 09:44:39 GMT Message-ID: <37b2e7$d89@hrz-ws11.hrz.uni-kassel.de> Reply-To: LitProg@SHSU.edu, knobi@architektur.uni-kassel.de To: LitProg@SHSU.EDU Hi there! I`m searching for any kind of information, documentation or literatur of programming modem - and fax software. Please send me an email! Thanks... Kn --- >< >< >< >< >< >< >< >< >< >< >< >< >< >< >< >< >< >< >< >< >< >< >< >< >< Frank Knobloch Tel: ++49-561-283969 (Office) >< >< Schoenfelder Str. 35 ++49-561-26048 (Private) >< >< 34121 Kassel Fax: ++49-561-283969 >< >< GERMANY email: knobi@architektur.uni-kassel.de >< >< >< >< >< >< >< >< >< >< >< >< >< >< >< >< >< >< >< >< >< >< >< >< >< ================================================================================ Archive-Date: Tue, 11 Oct 1994 14:01:02 CDT Sender: owner-litprog@SHSU.edu From: matomira@di.epfl.ch (Fernando Mato Mira) Reply-To: LitProg@SHSU.edu, matomira@DI.EPFL.CH Subject: liprog tool with plain comment output? Date: 11 Oct 1994 18:26:46 GMT Message-ID: <37eld6$n0a@disunms.epfl.ch> MIME-Version: 1.0 Content-Type: text/plain; charset=iso-8859-1 Content-Transfer-Encoding: 8bit To: LitProg@SHSU.EDU Hello, Is there any litprog tool that will give me a nice lisp file with comments but no LaTeX commands? SchemeWEB either strips off all comments, or leaves all the mess in. It's OK if it doesn't pretty print, provided it doesn't tangle the code, either. Thanks, -- F.D. Mato Mira http://ligwww.epfl.ch/matomira.html Computer Graphics Lab matomira@epfl.ch EPFL FAX: +41 (21) 693-5328 ================================================================================ Archive-Date: Tue, 11 Oct 1994 14:20:22 CDT Sender: owner-litprog@SHSU.edu Date: Tue, 11 Oct 94 13:20:21 MDT From: "Nelson H.F. Beebe" Reply-To: LitProg@SHSU.edu, beebe@MATH.UTAH.EDU To: LitProg@SHSU.edu CC: beebe@math.utah.edu Subject: Literate Programming: call for bibliographic entries Message-ID: The most recent version of litprog.bib, 1.51, contains 96 entries, 46 of which have added or updated since 1-Aug-1994. One of the more recent ones is this very interesting paper that I strongly recommend to LITPROG list readers: @String{j-IEEE-SOFTWARE = "IEEE Software"} @Article{Ramsey:j-IEEE-SOFTWARE-11-5-97, author = "Norman Ramsey", title = "Literate Programming Simplified", journal = j-IEEE-SOFTWARE, year = "1994", volume = "11", number = "5", pages = "97--105", month = sep, acknowledgement = ack-nhfb, bibdate = "Wed Sep 07 20:28:11 1994", } Can those of you who collect literate programming literature please fetch the most recent bibliography from ftp.math.utah.edu:/pub/tex/bib/litprog.* or from any of the hosts which mirror it ("finger ctan@pip.shsu.edu" for a list of Comprehensive TeX Archive Network hosts, or the huge Computer Science bibliography archive on ftp.ira.uka.de), and send me BibTeX entries for any publications that you discover are missing. A project like this needs the help of a lot of people, and we can all benefit from our collaboration. Take heart: pleas like this one appear less frequently than fund drives on your local public radio and television stations, and don't even cost you money. ======================================================================== Nelson H. F. Beebe Tel: +1 801 581 5254 Center for Scientific Computing FAX: +1 801 581 4148 Department of Mathematics, 105 JWB Internet: beebe@math.utah.edu University of Utah Salt Lake City, UT 84112, USA ======================================================================== ================================================================================ Archive-Date: Tue, 11 Oct 1994 15:18:28 CDT Sender: owner-litprog@SHSU.edu Message-ID: <199410112018.AA08861@noc.BelWue.DE> From: Aaron "Optimizer" Digulla Reply-To: LitProg@SHSU.edu, digulla@FH-KONSTANZ.DE Subject: CWEB and LaTeX2e To: LitProg@SHSU.edu Date: Tue, 11 Oct 94 21:14:01 MEZ Hello, I have written a LaTeX2e style for CWEB which needs only a mini-patch in the cweb-sources to work (it even doesn't need that, but you have to patch it if you want to use MakeIndex, too). The patch renames the extensions of the index- and toc-files generated by CWEB. Now I have come over quite a few obstacles in CWEB which make it uncomfortable to use. I'm looking for a tool that can format text as CWEB does (ie. put keywords in boldface, etc), creates an index with all identifiers (underlining the definition) and such. What I want, too (and what CWEB can't really do) is a tool that can do this: text text text @*cweb node. @c int foo (int bar) @- text text text ie. that can put a node from CWEB into some other text ! The text should be formatted normally, but all between @* and @- should be formatted by CWEB. Is there any such thing ? Furthermore, I would like to have some advice how to make TeX breaks the pages (and where). Right now, I still get ugly pagebreaks, e.g. between the last line of a struct-definition and the }; :( I have put a \nopagebreak and \penalty 10000 in there, but to no avail. When I say "\def\everypar{\penalty 10000}", it works, but then TeX is not allowed to break the page anymore ! (I have set \interlinepenalty to 9999 to discourage pagebreaks inside paragraphs). Anyone may help ? I can send you my CWEB.sty if you want to try yourself. -- Aaron "Optimizer" Digulla. Author of XDME "(to) optimize: Make a program faster by improving the algorithms rather than by buying a faster machine." ================================================================================ Archive-Date: Tue, 11 Oct 1994 15:36:58 CDT Sender: owner-litprog@SHSU.edu Message-ID: <199410112036.AA10041@noc.BelWue.DE> From: Aaron "Optimizer" Digulla Reply-To: LitProg@SHSU.edu, digulla@FH-KONSTANZ.DE Subject: CWEB and LaTeX2e To: LitProg@SHSU.edu Date: Tue, 11 Oct 94 21:14:01 MEZ Hello, I have written a LaTeX2e style for CWEB which needs only a mini-patch in the cweb-sources to work (it even doesn't need that, but you have to patch it if you want to use MakeIndex, too). The patch renames the extensions of the index- and toc-files generated by CWEB. Now I have come over quite a few obstacles in CWEB which make it uncomfortable to use. I'm looking for a tool that can format text as CWEB does (ie. put keywords in boldface, etc), creates an index with all identifiers (underlining the definition) and such. What I want, too (and what CWEB can't really do) is a tool that can do this: text text text @*cweb node. @c int foo (int bar) @- text text text ie. that can put a node from CWEB into some other text ! The text should be formatted normally, but all between @* and @- should be formatted by CWEB. Is there any such thing ? Furthermore, I would like to have some advice how to make TeX breaks the pages (and where). Right now, I still get ugly pagebreaks, e.g. between the last line of a struct-definition and the }; :( I have put a \nopagebreak and \penalty 10000 in there, but to no avail. When I say "\def\everypar{\penalty 10000}", it works, but then TeX is not allowed to break the page anymore ! (I have set \interlinepenalty to 9999 to discourage pagebreaks inside paragraphs). Anyone may help ? I can send you my CWEB.sty if you want to try yourself. -- Aaron "Optimizer" Digulla. Author of XDME "(to) optimize: Make a program faster by improving the algorithms rather than by buying a faster machine." ================================================================================ Archive-Date: Tue, 11 Oct 1994 16:46:28 CDT Sender: owner-litprog@SHSU.edu From: matomira@di.epfl.ch (Fernando Mato Mira) Reply-To: LitProg@SHSU.edu, matomira@DI.EPFL.CH Subject: Re: liprog tool with plain comment output? Date: 11 Oct 1994 20:22:55 GMT Message-ID: <37es6v$p2j@disunms.epfl.ch> MIME-Version: 1.0 Content-Type: text/plain; charset=iso-8859-1 Content-Transfer-Encoding: 8bit To: LitProg@SHSU.EDU In article <37eld6$n0a@disunms.epfl.ch>, matomira@di.epfl.ch (Fernando Mato Mira) writes: > Is there any litprog tool that will give me a nice lisp file > with comments but no LaTeX commands? SchemeWEB either strips off > all comments, or leaves all the mess in. > It's OK if it doesn't pretty print, provided it doesn't > tangle the code, either. Or one that cleans up only the lisp documentation strings, and with an emacs mode that lets me hide a. the LaTex commands only b. WEB stuff I'm not interested in (long discussions, etc). Thanks again, -- F.D. Mato Mira http://ligwww.epfl.ch/matomira.html Computer Graphics Lab matomira@epfl.ch EPFL FAX: +41 (21) 693-5328 ================================================================================ Archive-Date: Tue, 11 Oct 1994 23:49:40 CDT Sender: owner-litprog@SHSU.edu From: norman@flaubert.bellcore.com (Norman Ramsey) Reply-To: LitProg@SHSU.edu, norman@FLAUBERT.BELLCORE.COM Subject: Re: liprog tool with plain comment output? Date: 12 Oct 1994 00:25:44 GMT Message-ID: <37fae8$a4t@lowell.bellcore.com> CC: Fernando Mato Mira To: LitProg@SHSU.EDU In article <37eld6$n0a@disunms.epfl.ch>, Fernando Mato Mira wrote: > Is there any litprog tool that will give me a nice lisp file >with comments but no LaTeX commands? I'm not quite sure what you're asking, but the nountangle script distributed with noweb will take a literate program and turn it into a nicely indented source file with commments (and no LaTeX goo). noweb is available from CTAN (from Switzerland try ftp.uni-stuttgart.de). ================================================================================ Archive-Date: Wed, 12 Oct 1994 02:52:53 CDT Sender: owner-litprog@SHSU.edu From: iggjacob@sgi16 (Jacob Nielsen (c898594)) Reply-To: LitProg@SHSU.edu, iggjacob@SGI16 Subject: Re: FWEB Date: 12 Oct 1994 07:34:39 GMT Message-ID: <37g3if$63n@unidhp.uni-c.dk> To: LitProg@SHSU.EDU >>>> John == John S. Robinson (jsrobin@afterlife.ncsc.mil) John> I received a partial solution to my problem of using LaTeX mode John> in fweb by e-mail . This solution, described below, still yields John> the following errors: fweave testfile.web This is FWEAVE [UNIX John> version 1.40 (October 30, 1993)]. Reading John> /user/jsrobin/fweb.sty... (No testfile.aux file.) Reading John> testfile.web... *1 *22 Writing testfile.tex... *1 *22 Writing John> testfile.idx...testfile.scn... Done. CPU = 0.3 sec.; REAL = John> 0.4 sec. CPU/REAL = 71.7%. [FWEAVE: No errors were found.] John> //ValueAssignment/fweb 4097 > latex testfile.tex This is TeX, John> Version 3.1415 (C version 6.0) (testfile.tex LaTeX2e John> <1993/12/24> PRELIMINARY TEST RELEASE John> (/usr/TeX/lib/texmf/tex/inputs/fwebmacL.sty LaTeX error. See John> LaTeX manual for explanation. Type H for immediate John> help. ! The font family command \rm is not defined.. John> \@latexerr ...rcontextlines \m@ne \errmessage {#1} \endgroup John> l.43 ^^I\fontsize{10}{12pt}\rm % The standard font for bulk of John> document. ? If you wonder why LaTeX2e doesn't find the \rm font family, that's because the the way fonts are loaded has changed between LaTeX 2.09 (the standard right now) and LaTeX2e (the one you have --- the next standard LaTeX on the way to LaTeX3) The font names has also changed. Perhaps someone with LaTeX2e-experience could elaborate (and correct me if I've got it all wrong :) ? [solution deleted] Jacob -- Jacob Nielsen iggjacob@bbar.dtu.dk ================================================================================ Archive-Date: Wed, 12 Oct 1994 07:59:34 CDT Sender: owner-litprog@SHSU.edu From: eric@american.edu (Eric Prestemon) Reply-To: LitProg@SHSU.edu, eric@AMERICAN.EDU Subject: not-small C program with noweb. thoughts? Date: 12 Oct 1994 11:58:09 GMT Message-ID: <37gj0h$pv1@paladin.american.edu> To: LitProg@SHSU.EDU I am making my first foray into writing a more-than-trivial C program and my first foray into noweb. I have a few questions. Are there examples of finished C/noweb programs out there, beyond what is in the noweb distribution? Specifically, I am interested in how people write functions and function calls cleanly (rather than inlining a chunk, which seems the more natural *WEB way to do things). Is noweb less usable than, say, CWEB or FWEB for this kind of thing? The printed output isn't too critical to me; only I and whoever maintains the program after I stop working on it will ever see it. I don't plan to spend much (any) time customizing the output. Also, a DOS implementation is handy, though much of my development is on a unix machine. For these reasons, and my plan to use multiple output files, I think noweb is best, but I'm open to other ideas. (As an aside, I'm not much of DOS guru, and the dosnoweb-2.5a distribution didn't include a cpif, as far as I can tell. Is there an easy way to do such a thing in DOS? Between having multiple output files and a slow PC, only compiling the source files that change would save me a lot of time.) Is there a good emacs mode for editing noweb files? I've been using C mode, which I guess is okay, but it's not perfect. Diving into the cc-mode.el code to make changes seems too difficult. This isn't critical, cc-mode gets the C parts right, and I just have to convince it to let me enter certain things in the text. Thanks for any help or any other comments, -Eric ================================================================================ Archive-Date: Wed, 12 Oct 1994 07:59:52 CDT Sender: owner-litprog@SHSU.edu From: schrod@iti.informatik.th-darmstadt.de (Joachim Schrod) Reply-To: LitProg@SHSU.edu, schrod@ITI.INFORMATIK.TH-DARMSTADT.DE Subject: Re: FWEB Date: 12 Oct 1994 12:40:39 GMT Message-ID: <37glg7$lf2@rs18.hrz.th-darmstadt.de> To: LitProg@SHSU.EDU In article <37g3if$63n@unidhp.uni-c.dk>, iggjacob@sgi16 (Jacob Nielsen (c898594)) writes: > If you wonder why LaTeX2e doesn't find the \rm font family, that's > because the the way fonts are loaded has changed between LaTeX 2.09 > (the standard right now) and LaTeX2e (the one you have --- the next > standard LaTeX on the way to LaTeX3) The font names has also changed. I have never met any difference. One can use \rm both in compatibility mode and in all standard classes. > Perhaps someone with LaTeX2e-experience could elaborate (and correct > me if I've got it all wrong :) ? I won't elaborate on any problems with a `PRELIMINARY TEST RELEASE' of LaTeX2e that is known to have **many** bugs, some of them leading to obscure reactions. He should install the current version, try it again, and then come back if the error message still is there. Joachim -- =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= Joachim Schrod Email: schrod@iti.informatik.th-darmstadt.de Computer Science Department Technical University of Darmstadt, Germany ================================================================================ Archive-Date: Wed, 12 Oct 1994 08:34:31 CDT Sender: owner-litprog@SHSU.edu From: paul@heino.ibh.rwth-aachen.de (Paul Foerster) Reply-To: LitProg@SHSU.edu, paul@HEINO.IBH.RWTH-AACHEN.DE Subject: URGEND!! Request: Literature on program testing needed. Date: Wed, 12 Oct 1994 13:25:55 GMT Message-ID: MIME-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit To: LitProg@SHSU.EDU Hi everybody out there, i have to give a lecture about program testing. I have to talk about how it should be done, what methodologies there are to verify the code is correct, etc. Thus my request. German literature on this topic is generally preferred though i'll gladly accept any other pointers too. I don't know whether the groups i posted this to are the correct ones. So if not, please don't flame me to death. This is an urgend request because i only have 2 weeks to get the darn thing done. And for the german readers: Tut mir leid, dass ich hier in Englisch poste, aber die Gruppenliste enthaelt nun einmal groesstenteils Englisch-sprachige Gruppen. Anyway, any pointers, hints, clues, etc. on this topic are welcome. Please send everything to my email-address below. Please do _NOT_ post because i probably won't scan the whole groups again because i simply don't have the time ;( Cheers, Paul P.S. Don't flame me for my HUGE signature! (I'm normally in alt.ascii-art and rec.arts.ascii) -- .odbo. .od88888888bo. Paul Foerster .od8888888888888888bo. .od888888888888888888888888bo. paul@heino.ibh.rwth-aachen.de od88888888888888888888888888888888bo `~888888888888888888888888888888~' `~888888888888888888888888~'| "Beam me up Scotty, there's no `~888888888888888888~' | intelligent life down here!" |`~888888888888~'| | \ `~888888~' / A `-_ `~~' _-' H `--____--' ================================================================================ Archive-Date: Wed, 12 Oct 1994 17:28:24 CDT Sender: owner-litprog@SHSU.edu From: kap1@wimpy.cpe.uchicago.edu (Dietrich J. Kappe) Reply-To: LitProg@SHSU.edu, kap1@WIMPY.CPE.UCHICAGO.EDU Subject: tonu: some fixes Message-ID: Date: Wed, 12 Oct 1994 21:19:53 GMT To: LitProg@SHSU.EDU A couple of goofs crept into the first release of tonu. One goof was that it printed out where on the line stack an error occurred, rather than its line number in the input file. A few typos were also corrected. Here then is the source for tonu, a tool for converting non-literate programs into nuweb-literate ones. --------- \documentstyle[rcs,times2,9pt,fullpages]{article} \RCS$Id: tonu.w,v 1.2 1994/10/12 20:07:08 kap1 Exp $ \RCS$Date: 1994/10/12 20:07:08 $ \title{Tonu\\ Going From Pre-Literate to Literate} \author{\sl Dietrich Kappe} \date{(Version \RCSId )\\ Generated on \RCSDate} \begin{document} \pagestyle{myheadings} \markboth{tonu}{\today} \maketitle \tableofcontents \section{Introduction} I often convert pre-literate programs to literate ones. By cutting and pasting like a madman, I reorganize the source into the beginnings of a web-like document. It occurred to me that walking through the code and marking up which portions belonged in which scraps, was a far more efficient process. All I needed now was a tool that would read my marked up copy and produce a web-like document from it. I chose perl as the implementation language, both for its excellent text handling capabilities and its wide availability. I chose {\tt nuweb} as the Literate Programming tool, because it is what I use. Marking up a source text is best explained by providing a simple example. The following is the original source text: @o example.c @{ #include main() { printf("Hello with an @@ sign.\n"); } @} Here is a markup of the file: @o example.tonu @{ <> #include <<>> <
> main() { <> printf("Hello with an @@ sign.\n"); <<>> } <<>> @} When run through the {\tt tonu} processor, we get the following: @o example.w @{ @@d Includes for example.c @@{ #include @@} @@d Print the message @@{ printf("Hello with an @@@@ sign.\n"); @@} @@d Main program @@{ main() { @@ } @@} @@o example.c @@{ @@ @@
@@} @} Scrap delimiters begin in the first column of a line with \verb|<<|, followed by the scrap name, and ended by a \verb|>>|. The delimiter must fit on one line. The end of scrap delimiter is \verb|<<>>| at the beginning of a line, and ends the innermost (or most recently opened) scrap. When a scrap is ended, it is output as a {\tt nuweb} format scrap. Note that the \verb|@@| signs are escaped for {\tt nuweb}. \subsection{File Names} {\tt Tonu} operates by taking a file name from the command line, and writing the converted file to standard out. The \verb|@@o| scrap name comes from the name of the original file. \section{The Algorithm} I decided to use a primitive PDA for this job. As we read in lines, we push them onto a stack. When we run into a beginning of scrap marker, we push its location in the line stack onto a separate marker stack. When we run into a end of scrap mark, pop the last marker off the marker stack and use it to index to print out the top of the line stack from that index on. Finally we pop off that same portion of the line stack, and replace it with a {\tt nuweb} reference to that scrap. @d Push them lines @{ while () { $lcount++; # one more line s/\@@/\@@\@@/g; # safety first to escape nuweb special character push(@@lines,$_); # push line onto stack if (m/^<<.+>>/) { # begin scrap (ignore trailing garbage after >>) push(@@markers,$#lines); # save begin marker } elsif (m/^<<>>/) { # end of scrap (ignore trailing garbage) @ @ } } @ @ @} If we don't have any markers on the marker stack, that means we have no open scraps. Thats a fatal error. Otherwise, \verb|$marker| contains the line stack location of the beginning of scrap tag. On error, we print out where the error occurred. @d Pop off marker and handle error @{ $marker = pop(@@markers); if (!defined($marker)) { # no open scrap print STDERR "No open scrap to be closed at line ",$lcount, " in file $prog.\n"; exit(1); # No point in going on } @} We want to name the scrap we are printing out. That information, the name, is buried in the beginning of scrap marker. We have to extract it, print a nuweb style scrap header with it, substitute a nuweb style reference into its original location, and wipe out the rest of the stack following it. Piece of cake, eh? In perl it is. Note that we do not print out the last line, as that contains the end of scrap marker. @d Print out the scrap and substitute a reference for it @{ $lines[$marker] =~ m/^<<(.+)>>/; # get the name $name = $1; print "\@@d $name\n\@@{\n"; # header for ($i=$marker+1;$i < $#lines;$i++) { # don't do the last, end of scrap line print $lines[$i]; # print out the scrap } print "\@@}\n\n"; # close scrap # replace with ref and wipe the stack $lines[$marker] = "\@@<" . $name . "\@@>\n"; # replace it with the ref $#lines = $marker; # wipe out the rest of the stack @} When we reach an end of file, we verify that all scraps were closed, by checking that the marker stack is empty, then print out the line stack inside of the \verb|@@o| scrap. @d Verify that all scraps were closed @{ if ($#markers > -1) { # the marker stack is not empty print STDERR "There were ", $#markers +1, " open scraps in file ", $prog, ".\n"; exit(1); } @} @d Print out file scrap @{ print "\@@o $prog\n\@@{\n"; # print the header for $elt (@@lines) { print $elt; # output the lines } print "\@@}\n\n"; # close scrap @} \section{The Command Line} Now for the usual business of grabbing command line arguments, opening files, and printing out a usage message. @d Try to open the file and set the file name @{ $usage = "Usage: tonu filename\n"; if ($#ARGV != 0) { # we want an array of one file name print STDERR $usage; exit(1); } if (!open(PROG,$ARGV[0])) { # unsuccessful open print STDERR "Couldn't open file $ARGV[0]. $!\n"; exit(1); } # set the file name $ARGV[0] =~ m,([^/]+)$,; # get all but path $prog = $1; # set the file name to that @} \section{Tonu: the File} Lets put it all together in one happy Perl script. @o tonu @{#!/usr/local/bin/perl @ @ exit(0); @} \section{Conclusions} The program isn't perfect but provides me with a useful tool for converting pre-literate programs into literate ones. I release this code into the puiblic domain in the hopes that someone will find it useful, and perhaps improve upon it. \section{Index} \subsection{Files} @f \subsection{Macros} @m \end{document} ---------- -- Dietrich "The man who squared the SPC" Kappe kap1@wimpy.cpe.uchicago.edu -finger for PGP public key- ================================================================================ Archive-Date: Wed, 12 Oct 1994 18:53:44 CDT Sender: owner-litprog@SHSU.edu From: norman@flaubert.bellcore.com (Norman Ramsey) Reply-To: LitProg@SHSU.edu, norman@FLAUBERT.BELLCORE.COM Subject: Re: not-small C program with noweb. thoughts? Date: 12 Oct 1994 20:37:50 GMT Message-ID: <37hheu$gi9@lowell.bellcore.com> CC: Eric Prestemon , bed_gdg@SHSU.edu, mff@cs.princeton.edu To: LitProg@SHSU.EDU In article <37gj0h$pv1@paladin.american.edu>, Eric Prestemon wrote: >Are there examples of finished C/noweb programs out there, beyond what >is in the noweb distribution? This is a good question. A while back (last year?) there was some idle talk about setting up an archive of literate programs for people to read. This would let people read some literate programs and compare tools and techniqus. George Greenwade even said he might be able to provide space for such an archive after his new disk arrived. This is a task worth doing, but it would take nontrivial work to set up and maintain such an archive. (For example, do you keep source? .tex? postscript? all of the above.) Any volunteers? To answer your specific question, I don't know of any well-written C programs using noweb that are readily available. The best-written noweb program I have seen is about to be published as a book, but you can't get it yet: @book{fraser:retargetable:book, author="Christopher W. Fraser and David R. Hanson", title="A Retargetable {C} Compiler: Design and Implementation", publisher="Benjamin/Cummings", address="Redwood City, CA", year=1995, note="ISBN 0-8053-1670-1, in press" } Don Knuth's latest book, The Stanford GraphBase, contains a number of CWEB programs that are worth some study. If you're learning C and literate programming, reading CWEB and writing noweb should present you no problems (writing CWEB is another story). Marcus Speh has a few examples on the WWW; try http://info.desy.de/user/projects/LitProg.html. >Is noweb less usable than, say, CWEB or FWEB for this kind of thing? I claim noweb is *more* usable than CWEB or FWEB. See my articles in the September 1994 IEEE Software or the July 1991 Software---Practice & Experience. >Is there a good emacs mode for editing noweb files? There are some emacs modes, including one distributed with noweb, but I think the world is still waiting for a good one... Norman ================================================================================ Archive-Date: Thu, 13 Oct 1994 12:17:51 CDT Sender: owner-litprog@SHSU.edu Date: Thu, 13 Oct 94 13:17:52 EDT From: Lee Wittenberg Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET To: LitProg@shsu.edu, eric@american.edu Subject: Re: not-small C program with noweb. thoughts? Message-ID: eric@american.edu writes: > Are there examples of finished C/noweb programs out there, beyond what > is in the noweb distribution? Specifically, I am interested in how > people write functions and function calls cleanly (rather than inlining > a chunk, which seems the more natural *WEB way to do things). I don't know of any, unless you count the C++ programs in the DOS distribution. One of these days I hope to get some more samples to pub/leew/samples.LP at bart.kean.edu, but as of yet, all the C examples there use CWEB. The technique I generally use for C programs is an overall structure something like (I use this in CWEB, too): <<[[#include]] lines>> <> <> <> Then, whenever I define a function, I write 2 chunks. For example: <>= int func(int, int); <>= int func(int x, int y) { return x + y; /* what, you want a *real* function? */ } I find this technique works very well, particularly since the prototype and the function definition stay in close proximity in the web. If one changes, the appropriate change is easy to make to the other. > Is noweb less usable than, say, CWEB or FWEB for this kind of thing? The > printed output isn't too critical to me; only I and whoever maintains > the program after I stop working on it will ever see it. I don't plan to > spend much (any) time customizing the output. Also, a DOS implementation > is handy, though much of my development is on a unix machine. For these > reasons, and my plan to use multiple output files, I think noweb is > best, but I'm open to other ideas. In my experience, they are all equally usable. They each have their strengths and weaknesses. You pays your money and you takes your choice. noweb is probably the easiest of the three to learn, however. > (As an aside, I'm not much of DOS guru, and the dosnoweb-2.5a > distribution didn't include a cpif, as far as I can tell. Is there an > easy way to do such a thing in DOS? Between having multiple output > files and a slow PC, only compiling the source files that change would > save me a lot of time.) Barry Schwartz has written one for DOS, it just hasn't made it into the official DOS package yet (mea culpa). By the way, the current DOS package supports version 2.6c, and I recommend the upgrade. -- Lee ------------------------------------------------------------------------ Lee Wittenberg | Halavah is a form of pie, and it has a Computer Science Department | specific gravity of 3.1416 and a specific Kean College of New Jersey | heat of .31416 Union, NJ 07083 | USA | -- D. E. Knuth | "The Potrzebie System of Weights leew@pilot.njin.net | and Measures" (1957) ------------------------------------------------------------------------ ================================================================================ Archive-Date: Thu, 13 Oct 1994 14:26:47 CDT Sender: owner-litprog@SHSU.edu From: thinman@netcom.com (Technically Sweet) Reply-To: LitProg@SHSU.edu, thinman@NETCOM.COM Subject: Re: liprog tool with plain comment output? Message-ID: Date: Thu, 13 Oct 1994 18:30:11 GMT To: LitProg@SHSU.EDU matomira@di.epfl.ch (Fernando Mato Mira) writes: > Is there any litprog tool that will give me a nice lisp file >with comments but no LaTeX commands? SchemeWEB either strips off >all comments, or leaves all the mess in. > It's OK if it doesn't pretty print, provided it doesn't >tangle the code, either. I just added a set of functions which document various functions, variables, classes, methods, and modules: (doc-module module-name short-description . text ) (doc-class class-name parent . text ) (doc-method method-name class-name arguments . text ) (doc-function function-name arguments . text ) (doc-variable variable-name . text ) (doc-text . text) Where 'text' is one or more strings. I have an program which finds these all and spits out a troff document. I'll probably do an HTML version soon when I have mosaic. Cross-referencing the classes would be very cool. The code is straight Scheme, and (doc-*) are dummy functions which the above arguments for syntax-checking. -- Lance Norskog thinman@netcom.com Artisputtingtogether. Art s th ow n aw y. ================================================================================ Archive-Date: Thu, 13 Oct 1994 19:38:57 CDT Sender: owner-litprog@SHSU.edu From: jsrobin@afterlife.ncsc.mil (John S. Robinson) Reply-To: LitProg@SHSU.edu, jsrobin@AFTERLIFE.NCSC.MIL Subject: Re: FWEB Message-ID: <1994Oct14.002653.6032@afterlife.ncsc.mil> Date: Fri, 14 Oct 1994 00:26:53 GMT To: LitProg@SHSU.EDU In article <37glg7$lf2@rs18.hrz.th-darmstadt.de>, Joachim Schrod wrote: >In article <37g3if$63n@unidhp.uni-c.dk>, iggjacob@sgi16 (Jacob Nielsen (c898594)) writes: . . . . >I won't elaborate on any problems with a `PRELIMINARY TEST RELEASE' >of LaTeX2e that is known to have **many** bugs, some of them leading >to obscure reactions. He should install the current version, try it >again, and then come back if the error message still is there. > > Joachim > >-- Well Mr. Joachim, I have scotched one 11 hr work day installing and verifying the latest greatest version of TeX, LaTeX2e, MakeTeXPK, and xdvik. The end result thoroughly surprised me. The same error occurs. If you know a solution, I would truly appreciate the benefit of your experience. Do you use fweb? Have you ever had a similar problem? I have sought to do a very standard type of installation using the default locations such as /usr/local/lib/texmf . Thanks in advance for the solution I know the net will provide. -- ------------------------------------------------------------------------ Friends don't let friends do DOS. ================================================================================ Archive-Date: Fri, 14 Oct 1994 03:11:41 CDT Sender: owner-litprog@SHSU.edu From: royd@zapffe.mat-stat.uit.no (Roy Einar Dragseth) Reply-To: LitProg@SHSU.edu, royd@ZAPFFE.MAT-STAT.UIT.NO Subject: FWEB & LaTeX2e Message-ID: Date: Fri, 14 Oct 1994 08:03:44 GMT To: LitProg@SHSU.EDU Hello. I'm using FWEB v1.30 and here's what I did to fwebmac.sty to get it to work with LaTeX2e: 1. Changed (about line 40) from \ifx\selectfont\undefined\else \fontsize{10}{12pt}\rm % The standard font for bulk of document. \selectfont \fi to \ifx\selectfont\undefined\else \fontfamily{cmr} \fontsize{10}{12pt} % The standard font for bulk of document. \selectfont \fi 2. Added explicit font encoding to the fontdefinitions. (somewhere around line 140). This is what I ended up with: \else % NFSS \def\mainfont{\fontencoding{OT1}\fontfamily{\rmdefault}\fontseries{m}\fontshape{n}% \normalsize} \let\cmntfont\mainfont \def\eightrm{\fontencoding{OT1}\fontfamily{\rmdefault}\fontseries{m}\fontshape{n}% \footnotesize} \let\SC\eightrm \def\titlefont{\fontencoding{OT1}\fontfamily{\sfdefault}\fontseries{\bfdefault}% \fontshape{n}\Large} \def\ttitlefont{\fontencoding{OT1}\fontfamily{\ttdefault}\fontseries{m}\fontshape{n}% \Large} \def\tentex{\fontencoding{OT1}\fontfamily{\ttdefault}\fontseries{m}\fontshape{n}% \normalsize} \def\Csc{\fontencoding{OT1}\fontfamily{\rmdefault}\fontseries{m}\fontshape{\scdefault}% \normalsize} \def\tenbfit{\fontencoding{OT1}\fontfamily{\rmdefault}\fontseries{\bfdefault}% \fontshape{\itdefault}\normalsize} \def\seventi{\fontencoding{OT1}\fontfamily{\rmdefault}\fontseries{m}% \fontshape{\itdefault}\scriptsize} \def\sevenrm{\fontencoding{OT1}\fontfamily{\rmdefault}\fontseries{m}\fontshape{n}% \scriptsize} \def\sevenbf{\fontencoding{OT1}\fontfamily{\rmdefault}\fontseries{\bfdefault}% \fontshape{n}\scriptsize} \def\fiveti{\fontencoding{OT1}\fontfamily{\rmdefault}\fontseries{m}% \fontshape{\itdefault}\tiny} \def\fiverm{\fontfamily{\rmdefault}\fontseries{m}\fontshape{n}\tiny} \def\fivebf{\fontfamily{\rmdefault}\fontseries{\bfdefault}% \fontshape{n}\tiny} \def\tensy{\fontencoding{OMS}\fontfamily{cmsy}\fontseries{m}\fontshape{n}\normalsize} \def\pbf{\fontencoding{OT1}\fontfamily{\rmdefault}\fontseries{\bfdefault}\fontshape{n}% \selectfont} \def\ptt{\fontencoding{OT1}\fontfamily{\ttdefault}\fontseries{m}\fontshape{n}\selectfont} \fi 3. Added documentclass. This is not a good solution, you will have to manually change the 12pt option in fwebmac.sty, it cannot be set in fweb.sty. This is because in 2.09 it is a style file and in 2e it is a class option. Besides this is not needed to get fwebmac.sty running under LaTeX2e, but LaTeX is slower in compatability mode. (This is around line 870-880) \def\Wbegin[#1]#2#3#4#5#6{\edef\contentsfile{#5}% \def\readcontents{\input\contentsfile}% \Wequate#6 \ifLaTeXisloaded %%% A hack by royd@math.uit.no 5.9.94 \ifx\selectfont\undefined % For latex209 \documentstyle[#1]{#2} \else % For LaTeX2e \documentclass[12pt]{#2}% \usepackage{#1} \fi %%% \textwidth\pagewidth \textheight\pageheight \TeXindent#3 \begin{document} \pageno=2 \else This should be about all that is needed to be done. I've thrown away the original file so it is possible I've forgot something. I hope this will be useful, it works for me. -- ________________________________________________________________________ INSTITUTE OF MATHEMATICAL SCIENCES Dept. of Mathematics and Statistics University of Tromsoe, N-9037 Tromsoe, Norway, Tlf. +47 77 64 40 00, Fax +47 77 64 47 65 Roy Dragseth, Ph. D. st., direct call +47 77 64 40 31, E-mail: royd@math.uit.no ------------------------------------------------------------------------ ================================================================================ Archive-Date: Fri, 14 Oct 1994 09:29:26 CDT Sender: owner-litprog@SHSU.edu From: trashy@icicle.winternet.com (Barry Schwartz) Reply-To: LitProg@SHSU.edu, trashy@ICICLE.WINTERNET.COM Subject: Re: not-small C program with noweb. thoughts? Date: 14 Oct 1994 14:07:54 GMT Message-ID: <37m3bq$bfe@blackice.winternet.com> To: LitProg@SHSU.EDU In article <37gj0h$pv1@paladin.american.edu> eric@american.edu (Eric Prestemon) writes: ]Are there examples of finished C/noweb programs out there, beyond what ]is in the noweb distribution? Specifically, I am interested in how ]people write functions and function calls cleanly (rather than inlining ]a chunk, which seems the more natural *WEB way to do things). I haven't yet written any large programs with noweb, but even in small programs I don't depend too much on the chunk mechanism, unless the language makes subroutines ungainly. (Perl may exhibit this property.) I like to put C subprograms in two main chunks. First I present a prototype, and then the definition, adjacent to each other. The prototype goes into a chunk that gets tangled to near the top of the C file, and (in a multiple-file program) to a header file. The definition can go almost anywhere in the C file. Some languages are much easier to handle. In Icon, for instance, globals can go anywhere, and there's no need for prototypes or the like. This works out very well; you can just put all globals in the root chunk, or wherever you like. ](As an aside, I'm not much of DOS guru, and the dosnoweb-2.5a ]distribution didn't include a cpif, as far as I can tell. I have written a cpif in C/noweb, for MS-DOS, but it hasn't been released yet. However, there is nothing outlandish about the code; all I did was duplicate the functions of the shell script. -- Barry Schwartz at MedGraphics trashy@winternet.com ================================================================================ Archive-Date: Sun, 16 Oct 1994 12:43:03 CDT Sender: owner-litprog@SHSU.edu From: thompson@sun1.coe.ttu.edu Subject: comp.programming.literate FAQ Date: 15 Oct 1994 15:32:09 GMT Message-ID: Reply-To: LitProg@SHSU.edu, thompson@sun1.coe.ttu.edu To: LitProg@SHSU.EDU Archive-name: literate-programming-faq Last-modified: 1994/08/23 Version: 1.1.10 Welcome to the Literate Programming Frequently Asked Questions List ------------------------------------------------------------------- This version was created Tuesday, August 23, 1994, and should considered stale after 90 days. Information contained in this document is the best available at preparation. The original file was dated October 15, 1993 (just for historical purposes). Disclaimer: "This FAQ is presented with no warranties or guarantees of ANY KIND including correctness or fitness for any particular purpose. The author of this document has attempted to verify correctness of the data contained herein; however, slip-ups can and do happen. If you use this data, you do so at your own risk." Copyright 1993, 1994 David B. Thompson. All rights reserved worldwide. Permission is granted to copy this document for free distribution so long as it remains intact and unmodified. For other arrangements, contact the author/maintainer via email: thompson@sun1.coe.ttu.edu. What's New? ----------- + Add Fold2Web entry. + Correct noweb.el entry. (Thanks Dominique!) + Update nuweb.el entry. + Update SchemeWEB entry. + Update WWW and literate programming entry. + Update c2cweb entry. = ====================================================================== * Introduction or "What's this all about?" ------------------------------------------ This document is for new and experienced users of literate programming tools. The purpose is to explain the concept of literate programming and to provide a resource for locating files of interest to literate programmers and those interested in literate programming. The Literate Programming (LitProg) Frequently Asked Questions (FAQ) list is maintained by Dave Thompson, who can be reached at: thompson@sun1.coe.ttu.edu * Preferred mailing address for FAQ related comments/questions. wqdbt@ttacs1.ttu.edu * Forwarded to my pc. Comment and constructive criticism is welcome. Direct flames to /dev/null (or > nul if you're a msdos user! ;-) If you find an error, please report it. I'm particularly interested in establishing the locations of generally available literate programming tools. If you are the author of such a tool and wish to have it included in this list, please send email. Please note this is a work-in-progress. It is *not* complete, and probably will not be complete for some months. Nevertheless, the information contained herein may be useful to some. Use it as it is intended. - ---------------------------------------------------------------------- - Typography ------------ Major sections of the FAQ are divided by double lines (====). Minor sections and other divisions are separated by single lines (----). Major topics use a "* " as a leader. Minor topics use a "- " as a leader. This should simplify searching for topics. = ====================================================================== Table of Contents: ------------------ * Introduction, or "What's this all about?" - Typography * How do I get the FAQ? - Literate Programming FAQ - FWEB FAQ * Is there a newsgroup? (The comp.programming.literate newsgroup) * What internet nodes are of interest to literate programmers? * What is literate programming? * How do I begin literate programming? * What literate programming tools are available and where are they? - APLWEB - AWEB - CLiP - CWEB - FunnelWeb - FWEB - IMPACT - lit2x - Literate Programmer's Workshop (LPW) - MapleWEB - MWEB (Schrod/Detig) - MWEB (Sewell) - noweb - nuweb - ProTeX - RWEB - SchemeWEB - Spidery WEB - WEB - WinWordWEB * Are there other tools I should know about? - C2LaTeX - c2cweb - c2man - cnoweb - Fold2web - FunnelWeb mode - noweb.el - nuweb.el - TIE - Web mode * What other resources are available? - World Wide Web - TeX Resources - Virtual Coursework * Are there any code examples? - Examples included with developer's tools - Cameron Smith's KR-CWEB - Stanford GraphBase * Bibliographies. * How to anonymously ftp. * Acknowledgements. * End notes. = ====================================================================== * How do I get the FAQ? ----------------------- - Literate Programming FAQ -------------------------- You have many ways to get a current copy of this FAQ. One is to use anonymous ftp (if you don't know how, see a later section in this FAQ) to connect to one of the Comprehensive TeX Arvchive Network (CTAN) sites or the Literate Programming Archive and retrieve a copy of the file. Open an ftp connection to one of the CTAN sites and retrieve the file: help/LitProg-FAQ (For more information on CTAN and the literate programming archive, see the section below entitled "Internet Nodes of Interest to Literate Programmers.") An alternative is to use the fileserver at Sam Houston State University (SHSU). Send a message to FILESERV@SHSU.EDU and include in your message: SENDME LITPROG.FAQ The file server will forward a copy of the file to you via email. - ---------------------------------------------------------------------- - FWEB FAQ ---------- Marcus Speh maintains the FWEB FAQ. The current version number is 1.29. It can be retrieved in the same way as this FAQ; either by anonymous ftp or through the SHSU file server. On the SHSU server, the file name is FAQ.FWEB. Invoke your ftp software, open a connection to NIORD.SHSU.EDU [192.92.115.8], attach to the directory FAQ, and transfer the file FAQ.FWEB. Alternatively, send a message to the file server, FILESERV@SHSU.EDU, and include the following text in a one line message: SENDME FAQ.FWEB The file server will send the current version of the file via email. The FWEB FAQ exists in various formats, including HyperText (see other resources below). In Europe, the complete distribution can also be obtained from ftp.desy.de [131.169.10.115] in directory /pub/faq/web/fweb/. It is also available from the literate programming archive (LPA) in the directory LPA/Documentation/faq/fweb (see the references to LPA below for more information). Also, Marcus Speh is looking for someone willing to take over the FWEB FAQ. The text of his email message follows... "Please add to the FWEB FAQ the note that I am looking for someone to take the maintenance of the FAQ over - I am ready to assist in any way whatsoever, including tons of mail, notes for v1.29->v1.30, Texinfo sources, a WWW server and Hypertextification etc." If you're interested, send mail to marcus@x4u2.desy.de and express your willingness to serve. = ====================================================================== * Is there a newsgroup? ----------------------- One of the most important resources is the literate programming newsgroup, comp.programming.literate. You can read this newsgroup using your standard reader. Altenatively, the newsgroup is gated to a mailing list hosted by George Greenwade and Sam Houston State University. You can subscribe by sending mail to the list-server, LISTSERV@SHSU.EDU, and include in the message one line of text: SUBSCRIBE LITPROG "your name in quotes" The list is unmoderated; messages sent to litprog@shsu.edu are automatically distributed to all subscribers and cross-posted to comp.programming.literate. Archives of the mailing list and newsgroup are maintained on niord.shsu.edu [192.92.115.8] in the directory litprog. = ====================================================================== * What internet nodes are of interest to literate programmers? -------------------------------------------------------------- The principal nodes of interest to literate programmers are the Literate Programming Archive (LPA hereafter) and the CTAN (Comprehensive TeX Archive Network). The Literate Programming Archive (LPA) is: Node: ftp.th-darmstadt.de [130.83.55.75] Directory: programming/literate-programming Notes: Fastest response during off-U.S. [yep] business hours. The CTAN sites are: ftp host IP CTAN root Institution and Sponsor ------------------------------------------------------------------------- ftp.tex.ac.uk 134.151.79.32 pub/archive Aston Univ./UK TeX U.G. ftp.dante.de 129.206.100.192 soft/tex DANTE e.V. ftp.shsu.edu 192.92.115.10 tex-archive Sam Houston State Univ. Other nodes and directories of interest include: Node: niord.shsu.edu [192.92.115.8] Directory: various (do some snooping!) Notes: Has a gopher server. Node: ftp.desy.de [131.169.10.115] Directory: pub/web. Various documents, samples, and the FWEB FAQ. Notes: Has a www server, http://info.desy.de:80/ = ====================================================================== * What is Literate Programming? ------------------------------- Literate programming is the combination of documentation and source together in a fashion suited for reading by human beings. In fact, literate programs should be enjoyable reading, even inviting! (Sorry Bob, I couldn't resist!) In general, literate programs combine source and documentation in a single file. Literate programming tools then parse the file to produce either readable documentation or compilable source. The WEB style of literate programming was created by D.E. Knuth during the development of his TeX typsetting software. All the original work revolves around a particular literate programming tool called WEB. Knuth says: The philosophy behind WEB is that an experienced system programmer, who wants to provide the best possible documentation of his or her software products, needs two things simultaneously: a language like TeX for formatting, and a language like C for programming. Neither type of language can provide the best documentation by itself; but when both are appropriately combined, we obtain a system that is much more useful than either language separately. The structure of a software program may be thought of as a web that is made up of many interconnected pieces. To document such a program we want to explain each individual part of the web and how it relates to its neighbours. The typographic tools provided by TeX give us an opportunity to explain the local structure of each part by making that structure visible, and the programming tools provided by languages such as C or Fortran make it possible for us to specify the algorithms formally and unambigously. By combining the two, we can develop a style of programming that maximizes our ability to perceive the structure of a complex piece of software, and at the same time the documented programs can be mechanically translated into a working software system that matches the documentation. Another author (Eric W. van Ammers) wrote me a short article treating his opinions on literate programming. The text follows: First observation on LP About 90% of the disussion on this list is about problems with applying some WEB-family member to a particular programming language or a special documentation situation. This is ridiculous, I think. Let me explain shortly why... Lemma 1: I have proposed for many years that programming has nothing to do with programming langauges, i.e. a good programmer makes good programs in any language (given some time to learn the syntax) and a bad programmer will never make a good program, no matter the language he uses (today many people share this view, fortunately). Lemma 2: Literate Programming has (in a certain way not yet completely understood) to do with essential aspects of programming. Conclusion 1: A LP-tool should be independent of programming language. Lemma 3: It seems likely that the so called BOOK FORMAT PARADIGM [ref. 1] plays an important role in making literate programs work. Lemma 4: There are very many documentation systems currently being used to produce documents in the BOOK FORMAT. Conclusion 2: A LP-tool should be independent of the documentation system that the program author whishes to use. My remark some time ago that we should discuss the generic properties of an LP-tool was based on the above observation. References: [1] Paul W. Oman and Curtus Cook. Typographical style is more than cosmetic. CACM 33, 5, 506-520 (May 1990) Second observation on LP The idea of a literate program as a text book should be extendend even further. I would like to see a literate program as an (in)formal argument of the correctness of the program. Thus a literate program should be like a textbook on mathematicics. A mathematical textbook explains a theory in terms of lemma and theorems. But the proofs are never formal in the sense that they are obtaind by symbol manipulation of a proof checker. Rather the proofs are by so called "informal rigour", i.e. by very precise and unambiguous sentences in a natural language. Eric W. van Ammers Department of Computer Science Wageningen Agricultural University Dreijenplein 2 E-mail: ammers@rcl.wau.nl 6703 HB Wageningen voice: +31 (0)8370 83356/84154 The Netherlands fax: +31 (0)8370 84731 = ====================================================================== * How do I begin literate programming? -------------------------------------- A recommended book is D.E. Knuth's collection of articles (1992) "Literate Programming," Center for the Study of Language and Information, Stanford University, ISBN 0-937073-80-6 (pbk). This book gives insight into Knuth's thoughts as he developed the web system of literate programming (and TeX for typesetting). It does not document methods for literate programming. A recommended book is Wayne Sewell's (1989) "Weaving a Program: Literate Programming in WEB," Van Nostrand Reinhold, ISBN 0-442-31946-0 (pbk). This book focuses on using Knuth's web system. Some talk exists in the newsgroup/mailing list for a Usenet University course in literate programming. I'm sure discussion of this topic will be welcomed. If you are interested, please participate. = ====================================================================== * What literate programming tools are available and where are they? ------------------------------------------------------------------- A significant number of tools for literate programming are available. Most have been ported from their original systems, so support multiple computer platforms. If you are the developer of such a tool, and would like to make the software freely available, please send me email and I'll reply with a form (like those below) for you to fill in. (Or short-circuit the process and kludge a form from below. :-) - ---------------------------------------------------------------------- - APLWEB -------- Developer: Christoph von Basum Version: Unknown Hardware: MSDOS Languages: IBM APL2 and STSC APL Formatter: Plain TeX Availability: Anonymous ftp from: LPA:/apl watserv1.uwaterloo.ca:/languages/apl/aplweb Readme: Unknown Description: None available. Support: Unknown Note: The status of this particular package is unknown. - ---------------------------------------------------------------------- - AWEB ------ Developer: Unknown Version: Unknown Hardware: Unknown Languages: Ada Formatter: Unknown Availability: Anonymous ftp from: LPA:/ada/web Readme: Unknown Description: None available Support: Not supported. - ---------------------------------------------------------------------- - CLiP ------ Developer: E.W. van Ammers and M.R. Kramer Version: Unknown Hardware: Vax/VMS, Unix, and MS-DOS Languages: Any programming language. Formatter: Any formatter (TeX, LaTeX, Troff, Runoff, etc) or any wordprocessor including WYSIWYG systems (Word Perfect, Win Word, Ami Pro, Word, etc.) Availability: Anonymous ftp from: sun01.info.wau.nl:/CLIP/ms_dos MS-DOS version sun01.info.wau.nl:/CLIP/vax_vms VAX/VMS version CTAN:/web/clip LPA:/machines/ms-dos LPA:/machines/vax Readme: With bundle above Description: CLiP does not use explicite commands to perform the extraction process. Rather it recognizes pseudostatemens written as comments in the programming language in question. CLiP distinguishes pseudostatments from ordinary comments because the former comply with a a particular style. This style can be adjusted to suit virtually any programming language. The CLiP approach to LP makes the system extremely versatile. It is independent of programming language and text processing environment. We designed CLiP to be compatible with hypertext systems as well but we have not yet experimented with this form of documentation. Features: + CLiP imposes virtually no limitations on the text-processing system used to produce the documentation. If the text-processor supports these items you can + structure the documentation according to your own taste. + include drawings, pictures, tables etc. + disclose your documentatio my means of X-ref tables, Indexes, Table of contents, Table of tables, Table of figures, etc. + typeset the documented code. + Extracts any number of modules from a maximum of 64 source files. + No pretty-printing. Code from the source files is copied "as is" to the module. + Appearance of code segments in the documentation matches those of the modules to ease the identification of code segements. + Supports partially specified data types. + Comprehensive user manual (preliminary version) and technical description. - No automatic generation of a X-ref table for program identifiers. Support: Bugs, problems and assistance by e-mail: ammers@rcl.wau.nl - ---------------------------------------------------------------------- - CWEB ------ Developer: Silvio Levy and D.E. Knuth Version: 3.0 Hardware: Unix systems (dos and amiga ports available) Languages: C and C++ Formatter: Plain TeX and LaTeX. Availability: Anonymous ftp from: labrea.stanford.edu:/pub/cweb LPA:/c.c++ CTAN:/web/c_cpp/cweb DOS version in CTAN:/web/c_cpp/cwb30p8c DOS version in LPA:/machines/ms-dos Amiga version CTAN:/web/c_cpp/AmigaCWEB Mac port of CTANGLE in LPA:/machines/mac LaTeX support in LPA:/c.c++ Readme: Bundled with above Description: No description provided. Support: Bugs to levy@math.berkeley.edu Note: A fork of CWEB 3.x was developed by Marc van Leeuwen which implements several changes to CWEB. It is available for anonymous ftp from ftp.cwi.nl:pub/cweb. The principle changes are: - Scans include files for typedef definitions - Grammar and formatting rules are well separated, allowing for run-time selection of a rule set (via command line option) - New manual. - ---------------------------------------------------------------------- - FunnelWeb ----------- Developer: Ross N. Williams: ross@guest.adelaide.edu.au Version: Unknown Hardware: MSDOS, Mac, VMS, Sun. Other ports reported. Languages: No restrictions. Formatter: Plain TeX for printing. Otherwise, no restrictions. Availability: Anonymous ftp from: CTAN:/web/funnelweb LPA:/independent ftp.adelaide.edu.au:/pub/funnelweb Readme: With bundle above. Description: FunnelWeb is a production-quality literate-programming tool that emphasises simplicity and reliability. Everything about FunnelWeb, from the simplicity of its language to the comprehensive tutorial in the user's manual, has been designed to make this as simple, as practical, and as usable a tool as possible. Features: + Provides a simple macro preprocessor facility. + Can produce typeset documentation. + Runs on Sun, VMS VAX, Macintosh, PC, and others. + Portable C source code distributed under GNU licence. + Comprehensive user's manual including tutorial. + Programming-language independent. + Can generate multiple output files. + Allows complete control over the output text. + Regression test suite with over 200 tests. + Fully worked example (in /pub/funnelweb/examples). - Requires TeX to produce typeset documentation. - Typesets program code using TT font only. Support: No formal support available. Mailing list maintained with about 50 subscribers. Informal assistance available from mailing list. - ---------------------------------------------------------------------- - FWEB ------ Developer: John A. Krommes Version: 1.30a (1.40 for the experienced, patient, and brave) Hardware: Unix, VMS, and DOS platforms (anything with ANSI C) Languages: C, C++, Fortran-77, Fortran-90, Ratfor, TeX; also, a language-independent mode. Formatter: Plain TeX and LaTeX. Availability: Anonymous ftp from: ftp.pppl.gov:/pub/fweb CTAN:/web/fweb LPA:/fweb DOS version in LPA:/machines/ms-dos Readme: In bundle with above. Description: It also has a well-developed user's manual and its own FAQ (see above). Beginning with 1.40, documentation is maintained in gnu texinfo format. It runs on most platforms: VMS, PC, UNIX, and pretty much anything that the GNU C compiler (GCC) is supported for. Features: + Processes multiple languages during a single run (so one can mix C and Fortran, for example). + Language-independent mode (v1.40). + Ability to turn off pretty-printing (v1.40). + Built-in Ratfor translator. + Built-in macro preprocessor (closely follows ANSI C, with extensions). + A style file that allows the user to adjust many parameters and behavior patterns of FWEB. + Various operator-overloading features that provide additional pretty-printing capabilities to languages such as C++ and Fortran-90. + Numerous miscellaneous features and command-line options. Support: Bug reports and suggestions to krommes@princeton.edu - ---------------------------------------------------------------------- - IMPACT -------- Developer: Timothy Larkin, from Levy/Knuth CWEB 3.1 Version: 1.0 Hardware: Macintosh; requires AppleEvents. Languages: C, C++ Formatter: TeX Availability: CTAN archives Readme: A short readme file is included in the SEA archive. Description: IMPACT implements CTangle from the Levy/Knuth CWEB 3.1. It operates as a foreground program, tangling files selected from the Mac File Picker. Or it can operate in the background, tangling files in response to odoc events sent by other applications, such as editors. Support: I welcome any reports of bugs. The product will be updated as new versions of the CWEB appear. Other features may be added as users suggest them. - ---------------------------------------------------------------------- - lit2x ------- Developer: Unknown Version: Unknown Hardware: Unknown Languages: Unknown Formatter: Unknown Availability: Anonymous ftp from: LPA:/independent Readme: Unknown Description: None available Support: Unknown - ---------------------------------------------------------------------- - Literate Programmer's Workshop (LPW) -------------------------------------- Developer: Norbert Lindenberg Version: 1.1 Hardware: Apple Macintosh Languages: C++, Object Pascal & others Formatter: self-contained WYSIWYG system Availability: Anonymous ftp from: LPA:/machines/mac CTAN:/web/lpw ftp.apple.com:/pub/literate.prog Readme: With bundle above. Also comes with 38-page manual. Description: The Literate Programming Workshop is an environment for the integrated development of program source text and documentation in combined documents. It consists of a WYSIWYG word processor based on a style sheet approach, a mechanism to extract parts of the text in a document, and a project management system that handles multi-document projects. The system is designed to be used in conjunction with the Macintosh Programmer's Workshop: it prepares raw source text for the MPW compilers, accepts MPW error messages, and shows them in the context of the original documents. Automatic indexing and hypertext features allow for easy access to both source text and documentation. LPW is shareware. Support: Bugs, problems, and questions to lpw@aol.com. - ---------------------------------------------------------------------- - MapleWEB ---------- Developer: Unknown Version: Unknown Hardware: Unknown Languages: Maple Formatter: Unknown Availability: Anonymous ftp from: LPA:/maple Readme: Unknown Description: None Support: Unknown - ---------------------------------------------------------------------- - MWEB (Schrod/Detig) --------------------- Developer: Joachim Schrod Version: Unknown Hardware: Unknown Languages: Modula-2 Formatter: Unknown Availability: Anonymous ftp from: LPA:/modula-2 Readme: Unknown Description: None Support: Not supported. - ---------------------------------------------------------------------- - MWEB (Sewell) --------------- Developer: Sewell Version: Unknown Hardware: Unknown Languages: Modula-2 Formatter: Unknown Availability: Anonymous ftp from: LPA:/modula-2 Readme: Unknown Description: None Support: Not supported. - ---------------------------------------------------------------------- - noweb ------- Developer: Norman Ramsey Version: 2.6 Hardware: Unix and DOS platforms. Languages: All programming languages. Formatter: Plain TeX, LaTeX, and HTML (Mosaic) formatters. Availability: Anonymous ftp from: CTAN:/web/noweb LPA:/independent DOS version also in LPA:/machines/ms-dos also bart.kean.edu:/pub/leew Last recourse, use bellcore.com:/pub/norman Readme: With bundle above. Description: noweb is designed to meet the needs of literate programmers while remaining as simple as possible. Its primary advantages are simplicity, extensibility, and language-independence. noweb uses 5 control sequences to WEB's 27. noweb now supports indexing and identifier cross-reference, including hypertext ``hot links'' courtesy of Mosaic. The simple noweb manual is only 2 pages; documenting the full power of noweave and notangle requires another 3 pages. noweb works ``out of the box'' with any programming language, and its formatter-dependent part is a 60-line nawk program. The primary sacrifice relative to WEB is the loss of prettyprinting. Support: email to the author - ---------------------------------------------------------------------- - nuweb ------- Developer: Preston Briggs: preston@cs.rice.edu Version: 0.87 Hardware: Unix systems: Sparcs, RS/6000s, HPs; (!) MSDOS and Amiga. Languages: Any programming language or combination of programming languages. Formatter: Latex Availability: Anonymous ftp from: Unix: CTAN:/web/nuweb DOS: CTAN:/web/nuweb-pc LPA:/independent Amiga: CTAN:/web/nuweb/nuweb_ami Amiga: wuarchive.wustl.edu/pub/aminet Readme: Send mail to preston@cs.rice.edu Description: A single program that takes a web file written in a combination of latex and any programming language(s) and produces a latex file that can be pretty printed and a set of files containing code for compilation/interpretation by the appropriate language processors. Strengths include speed, simplicity, multiple languages, nice indices and cross-references, latex. Doesn't require any special macros or macro files. Drawbacks: latex-dependent, no code pretty printing, harder to make indices than cweb. More good stuff: nice support for make, doesn't reformat source files, so they're easy to debug. Lots of control without too much effort. That is, it doesn't do too much! Future directions... Very little change planned, except perhaps refinements in the indexing software. Support: Hack it yourself or send e-mail to preston@cs.rice.edu - ---------------------------------------------------------------------- - ProTeX -------- Developer: Eitan Gurari Version: 1.1 (AlProTeX 1.2) Hardware: Any platform with TeX (ProTeX is written in TeX) Languages: Any language Formatter: TeX and LaTeX Availability: Anonymous ftp from: ftp.cis.ohio-state.edu : pub/tex/osu/gurari/ LPA:/independent Readme: Unknown Description: There is a book published on using ProTeX, @Book{Gurari:TLD94, author = "Eitan M. Gurari", title = "{\TeX} and {\LaTeX}: Drawing and Literate Programming", publisher = pub-MH, year = "1994", address = pub-MH:adr, bibdate = "Wed Sep 29 17:55:14 1993", acknowledgement = ack-nhfb, } Support: gurari@cis.ohio-state.edu - ---------------------------------------------------------------------- - RWEB ------ Developer: Unknown Version: Unknown Hardware: Unknown Languages: Unknown Formatter: Unknown Availability: Anonymous ftp from: LPA:/reduce Readme: Unknown Description: Web generator in AWK. Support: Unknown - ---------------------------------------------------------------------- - SchemeWEB ----------- Developer: John D. Ramsdell Version: 2.1 Hardware: Unix and DOS platforms Languages: Any dialect of Lisp. Formatter: LaTeX. Availability: The Unix version is in the Scheme Repository and it is available via anonymous ftp from: cs.indiana.edu:/pub/scheme-repository/utl/schemeweb.sh LPA:/lisp CTAN:/tex-archive/web/schemeweb The DOS version is part of the PCS/Geneva Scheme system which is available via anonymous ftp from: cui.unige.ch:/pub/pcs LPA:/machines/ms-dos Readme: In bundle with above. Description: SchemeWEB is a Unix filter that allows you to generate both Lisp and LaTeX code from one source file. The generated LaTeX code formats Lisp programs in typewriter font obeying the spacing in the source file. Comments can include arbitrary LaTeX commands. SchemeWEB was originally developed for the Scheme dialect of Lisp, but it can easily be used with most other dialects. Support: Bug reports to ramsdell@mitre.org. - ---------------------------------------------------------------------- - SpideryWEB ------------ Developer: Norman Ramsey Version: Unknown Hardware: Unix and DOS platforms Languages: Most Algol-like languages, including C, Ada, Pascal, Awk, and many others. Formatter: Plain TeX and latex for text formatters. Availability: Anonymous ftp from: CTAN LPA:/spiderweb Readme: In distribution. Description: A system for building language-dependent WEBs. Spider is frozen; no further development is planned. Support: Bug reports to spider-bugs@oracorp.com. - ---------------------------------------------------------------------- - WEB ----- Developer: Donald Knuth Version: Unknown Hardware: Unknown Languages: Pascal Formatter: TeX (of course! ;-) Availability: Anonymous ftp from: LPA:/pascal Readme: Unknown Description: This is the original software that started it all. The original TeX processor was written in WEB. Support: None known. - ---------------------------------------------------------------------- - WinWordWEB ------------ Developer: Lee Wittenberg Version: Unknown Hardware: Needs Microsoft Word for Windows, v.2.x, and, of course, MS-Windows 3.x. Languages: Any programming language. Formatter: Word for Windows 2.x for text formatting and file maintenance. Availability: Anonymous ftp from: bart.kean.edu:pub/leew LPA:/machines/ms-dos World-Wide Web (WWW) Readme: WORDWEB.DOC in the downloadable package describes the system. Description: WinWordWEB is a set of a Word for Windows macros (plus a paragraph style) that provide a crude literate programming environment. The ``look and feel'' of the system is based on Norman Ramsey's noweb, but can easily be modified to suit individual tastes. Support: None. WinWordWEB was written as a prototype to see if a WYSIWYG literate programming system was possible. It is intended as a jumping off point for future work by others. However, the system is surprisingly usable as it stands, and the author is interested in hearing from users (satisfied and dissatisfied). Anyone interested in actively supporting (and improving) the product should contact the author via email. = ====================================================================== * Are there other tools I should know about? -------------------------------------------- First of all, I'll list some not-quite-literate-programming tools. Some may consider these to be pretty-printers. Others may call them literate programming tools. In any event, they don't seem to be quite in the same category as the tools listed above, so I'll include them here. - C2LaTeX --------- Developer: John D. Ramsdell Version: Unknown Hardware: Unix Languages: C Formatter: LaTeX but it's easy to change the formatter. Availability: Anonymous ftp from omnigate.clarkson.edu:/pub/tex/tex-programs/c2latex. Readme: Absent. Documentation is in the C source for c2latex. Description: C2latex provides simple support for literate programming in C. Given a C source file in which the comments have been written in LaTeX, c2latex converts the C source file into a LaTeX source file. It can be used to produce typeset listings of C programs and/or documentation associated with the program. C2latex produces LaTeX source by implementing a small number of rules. A C comment that starts at the beginning of a line is copied unmodified into the LaTeX source file. Otherwise, non-blank lines are surrounded by a pair of formatting commands (\begin{flushleft} and \end{flushleft}), and the lines are separated by \\*. Each non-blank line is formatted using LaTeX's \verb command, except comments within the line are formatted in an \mbox. Support: Send bug reports to ramsdell@mitre.org. - ---------------------------------------------------------------------- - c2cweb -------- Developer: Werner Lemberg Version: 1.4 Hardware: DOS, OS/2, Unix (gcc) - CWEB source included Languages: C, C++ Formatter: TeX Availability: Anonymous ftp from CTAN:/web/c_cpp/c2cweb Readme: In distribution. Description: c2cweb will transform plain C or C++ code into a CWEB file to get a pretty formatted output. A modified CWEAVE (which transforms the CWEB file into a TeX file, see below) is included also. Support: Werner Lemberg - ---------------------------------------------------------------------- - c2man ------- Developer: Graham Stoney Version: 2.0 patchlevel 26 Hardware: Unix, MSDOS, OS/2. Languages: C Formatter: nroff -man, texinfo (requires yacc/byacc/bison, lex/flex, and nroff/groff/texinfo/LaTeX). Availability: Anonymous ftp from ftp.wustl.edu: /usenet/comp.sources.reviewed/volume03/c2man* ftp.informatik.uni-stuttgart.de: /pub/archive/comp.sources/reviewed/c2man* Readme: See distribution. Description: The primary philosophy here is to use the programming language as far as possible to express the programmer's intentions, and to use comments only when the programming language is not sufficiently expressive. A comment can then become part of the language grammar which is recognised by a "documentation compiler". This tool parses a superset of the programming language and can automatically generate documentation in human-readable form by associating the programmer's comments with the objects in the code by their context. Support: Actively supported; mailing list available: send "subscribe c2man " (in the message body) to listserv@research.canon.oz.au. - ---------------------------------------------------------------------- - cnoweb -------- Developer: Jim Fox Version: 1.4 (January 4, 1991) Hardware: Anything with C and TeX. Languages: C Formatter: Plain TeX. Availability: Anonymous ftp from: CTAN LPA:/c.c++ Readme: Unknown, cnoweb.tex contains documentation. Description: cnoweb is as it's name describes: write C, not web. No tangling or weaving is implemented. Documentation (between standard /* */ delimiteres) is written in TeX. cnoweb provides typesetting of documentation, an table of contents of routines, and pretty-printing of C source. Support: None known. - ---------------------------------------------------------------------- - Fold2Web ---------- Developer: Bernhard Lang Version: V0.8 Hardware: MSDOS Languages: All (must allow comment lines) Formatter: LaTeX Availability: Anonymous ftp from: kirk.ti1.tu-harburg.de (134.28.41.50) /pub/fold2web/readme /pub/fold2web/fold2web.zip Readme: In distribution Description: The idea behind the Fold2Web tool is the following: A programmer can write his program source with a folding editor and later map the folded source files automatically to WEB-files. The generated WEB-files can then be modified by inserting required documentations. The advantage by starting program developement with original sources is to get short design cycles during the compile/debug steps. By using a folding editor the global structuring information can be already captured in folds during this developement phase. Fold information is typically stored in comment lines and thus will not affect the efficiency of the compile/debug design cycle. Some folding editors and a folding mode for the emacs are available (e.g. see our FUE folding editor for MSDOS machines which is a modified micro emacs. Pick it at kirk in directory /pub/fold2web). After reaching a stable version of a program source its time to convert the source file to a WEB-file and do the program documentation. Fold2Web is written to convert folded source text of any programming language to nuweb files. The folded structure is kept by mapping folds to scraps. Fold markers which differ between languages due to different ways of specifying comments can be configured for each language. Good results can also achived when given but poor documented program sources have to be modified. Such sources can be folded using a folding editor to extract the global structures. This offers a global view to the program structures and help to understand its functionality. Furthermore the program code is not affected, only comment lines are inserted. Once folded the program source can be automatically translated to a WEB document using the above tool. Support: email to lang@tu-harburg.d400.de - ---------------------------------------------------------------------- - Funnelweb Mode ---------------- Developer: Daniel Simmons Version: Unknown Availability: Litprog archives (was in email) Anonymous ftp from: ftp.imada.ou.dk Description: The other day I did a quick hack to nuweb.el as included with the nuweb distribution so as to make a funnelweb-mode.el. I've only used it briefly, and I'm sure that it can be improved quite a bit. I've been thinking about adding support for folding on sections, a pull-down menu to select macro definitions (like the recent functions posted to gnu.emacs.sources for a C function definition pull-down menu) and some kind of tags support for funnelweb. Support: Unknown - ---------------------------------------------------------------------- - noweb.el ---------- Developer: Bruce Stephens Version: Unknown. Availability: LitProg archives (in an email message). Description: This is a very simple mode I just hacked up. There's a lot wrong with it, but I thought others may be interested, even as it stands. It *requires* text properties, and assumes those used in GNU Emacs 19.22; it'll quite likely work with Lucid Emacs, but I haven't tried it. I use it with auctex8.1 and cc-mode 3.229, both of which are loaded separately (I think my emacs is dumped with them, in fact). The idea is to have one mode (which calls itself c-mode, but actually has LaTeX-mode keybindings) generally (this means that the code is hilighted nicely), and have the code chunks use a different keymap. Support: Email to bruce@liverpool.ac.uk - ---------------------------------------------------------------------- - nuweb.el ---------- Developer: Dominique de Waleffe Version: 1.99 Availability: Anonymous ftp from: LPA CTAN Description: Provides a major mode extending Auctex for editing nuweb files. Main features (in 2.0): - Edit scrap bodies in a separate buffer in a different mode (selected using emacs defaults for files, specific indication -*-mode-*-, or a buffer-local variable) - Extends Auctex commands so that nuweb is called before LaTeX, - Easy navigation on scrap definition and use points. - Now creates an imenu (C-M-mouse1) with user index entries, macro definition positions and file definition positions. Support: Email to ddw@sunbim.be - ---------------------------------------------------------------------- - TIE ----- Developer: Unknown Version: Unknown Hardware: Unknown Availability: Anonymous ftp from: LPA:/Tools Readme: Unknown Description: This software merges change files. Support: Unknown - ---------------------------------------------------------------------- - Web mode ---------- Developer: Bart Childs Version: Unknown Tools supported: web, fweb, cweb, funnelweb Availability: Anonymous ftp from ftp.cs.tamu.edu:pub/tex-web/web/EMACS.web-mode thrain.anu.edu.au:pub/web/EMACS.web-mode Description: This version works with versions 18 and 19 of Emacs to be best of my knowledge. I have cleaned up a number of documentation items ... In the same directory is wm_refcard.tex which is an edited version of the famous one to include some web-mode commands. The files limbo* are related to its use and notice that half them have an uppercase L in them for LaTeX. The setup is based upon the fact that we (I am not alone here) primarily use FWEB for C and Fortran programming. We are using version 1.40 of FWEB although John Krommes warns that it is not mature and the manual is not yet updated. The info files are! We are using LaTeX almost exclusively. That will likely change and we will revert to version 1.30 if the final form of 1.40 cannot return to the simple section numbers and avoid the HORRIBLE LATEX 0.1.7.2.4.6 type section numbers. Support: Unknown = ====================================================================== * What other resources are available? ------------------------------------- - World Wide Web ---------------- An untapped resource (by me anyway ;-) is the World Wide Web. Marcus Speh has expended considerable effort in this regard. If you're connected to WWW, then access: http://info.desy.de:80/user/projects/LitProg.html If you aren't connected to WWW, telnet to info.cern.ch and explore. You can reach Marcus' literate programming pages by typing: go http://info.desy.de:80/user/projects/LitProg.html Help for people who have only Email and neither WWW nor telnet, can be obtained by Email from TEST-LIST@INFO.CERN.CH by sending a message, SEND , for example, SEND http://info.desy.de:80/user/projects/LitProg.html to retrieve the LitProg library page. A help file can be retrieved by sending a message to the list server above with the text HELP in the body of the message. Instructions will be returned by email. For literate programming documents, you can try anonymous ftp to ftp.desy.de [131.169.10.115] and get the file: /pub/userWWW/projects/Announce/LitProg.txt - ---------------------------------------------------------------------- - TeX Resources --------------- Another resource of interest to literate programmers is the info-tex mailing list. If you're using (La)TeX as your typsetting system and have access to internet, then you should investigate this mailing list. Mail list service is available through the SHSU list-server. To subscribe, send a message to LISTSERV@SHSU.EDU, and include in the message one line of text: SUBSCRIBE INFO-TEX "your name in quotes" The list is unmoderated; messages sent to info-tex@shsu.edu are automatically distributed to all subscribers and cross-posted to comp.text.tex. Archives of the mailing list and newsgroup are maintained on niord.shsu.edu [192.92.115.8] in the directory info-tex. Another reason the TeX resources should be important is that so many of the literate programming tools rely on either plain TeX or LaTeX as their text formatter. (La)TeX software systems exist for most computing platforms. These systems can be found on CTAN and other major archive sites. Use archie to find them or simply ftp to one of the CTAN sites and browse. - ---------------------------------------------------------------------- - Virtual Coursework -------------------- Marcus Speh plans an introductory course on Literate Programming on the Internet, part of the first semester of "Global Network Academy" [GNA], a non-profit corporation incorporated in the state of Texas, affilated with the Usenet University project. The texts/sample programs for this class will be made available via the World-Wide Web. A special room on GNA Virtual Campus will be staffed by a consultant in one to two hour shifts. Students with questions can telnet to the virtual campus and ask questions of the staff there. If you are interested in registering for the course either as a student or as a consultant, please contact marcus@x4u.desy.de. You will receive a standard reply message; no further action will be taken until June 94. Interested parties can check the hypertext notes for the completed C++ Course done in a similar fashion, at URL http://info.desy.de:80/pub/uu-gna/html/cc/index.html [Editor's note: Because of workload, Marcus requests that email inquiries be limited to a statement of interest for either a student or consultant position until June 1994.] = ====================================================================== * Are there any code examples? ------------------------------ Examples of web programs are included with the FWEB, CWEB, and noweb distributions. nuweb is written in itself. Cameron Smith converted the K&R calculator program into a literate program. It can be retrieved by anonymous ftp from: niord.shsu.edu [192.92.115.8] directory kr-cweb-sample as krcwsamp.zip or from LPA/Documentation Ross Williams has released a funnelweb example. You can retrieve this file from node ftp.adelaide.edu.au [129.127.40.3] as /pub/funnelweb/examples/except.* This file should be on CTAN as well. Lee Wittenberg has posted a few litprog examples. They are available via anonymous ftp from: bart.kean.edu:/pub/leew/samples.LP The Stanford GraphBase is a large collection of programs by Don Knuth for doing all kinds of computations and games with graphs; it is written in (Levy/Knuth) CWEB. More details in the distribution. It is available via anonymous ftp from: labrea.stanford.edu:/pub/sgb = ====================================================================== * Bibliographies ---------------- Nelson Beebe has collected an extensive bibliography treating literate programming. His work is available for anonymous ftp from ftp.math.utah.edu [128.110.198.2] in directory /pub/tex/bib as files: litprog.bib litprog.ltx litprog.twx. Although I have not verified this, LPA is an alternate source for these files. Note that they are updated frequently (Nelson says several times each week), so be sure to get a fresh copy before extensive use. Joachim Schrod indicates that these files may be updated daily and can be retrieved via anonymous ftp at LPA/documentation. = ====================================================================== * How to anonymously ftp ------------------------ Pretty much everything mentioned here is available by anonymous FTP. FAQ lists cross-posted to news.answers and rec.answers can be gotten from rtfm.mit.edu [18.181.0.24], under /pub/usenet/news.answers or under /pub/usenet/more.specific.group.name "anonymous FTP" is just a way for files to be stored where anyone can retrieve them over the Net. For example, to retrieve the latest version of the literate programming FAQ, do the following: > ftp rtfm.mit.edu /* connect to the site; message follows */ > anonymous /* type this when it asks for your name */ > /* type your address as the password */ > cd /pub/usenet /* go to the directory you want to be */ > cd comp.programming.literate /* one level down (no slash). */ > dir /* look at what's there */ > get literate-progamming-faq /* get the file; case-sensitive */ > quit /* stop this mysterious thing */ If your FTP program complains that it doesn't know where the site you want to use is, type the numerical address instead of the sitename: > ftp 18.181.0.24 /* connect with numerical address */ If you don't have ftp access, send e-mail to mail-server@rtfm.mit.edu with the single word "help" in the body of the message. Getting binary files (executables, or any compressed files) is only slightly more difficult. You need to set binary mode inside FTP before you transfer the file. > binary /* set binary transfer mode */ > ascii /* set back to text transfer mode */ FAQs and spoiler lists are generally ascii files; everything else is generally binary files. Some common extensions on binary files in archive sites are: .Z Compressed; extract with uncompress .tar.Z Compressed 'tape archive'; uncompress then untar or tar -xvf .gz or .z Gnu gzip; use gunzip (available from prep.gnu.ai.mit.edu) .sit (Mac) StufIt archive .zip Extract with Zip or Unzip .zoo Yet another archive/compress program .lhe (Amiga) ? .lzh Lha archive program. .arj (PC) Arj archive program. .exe (PC) Sometimes self-extracting archives-just execute them. .uue or .UUE Transfer as text file; use uudecode to convert to binary .hqx (Mac) BinHex format; transfer in text mode Generic help can be found in the FAQs of comp.binaries. for how to transfer, extract, and virus-check binary files. (At rtfm.mit.edu) If you can't FTP from your site, use one of the following ftp-by-mail servers: ftpmail@decwrl.dec.com ftpmail@src.doc.ic.ac.uk ftpmail@cs.uow.edu.au ftpmail@grasp.insa-lyon.fr For complete instructions, send a message reading "help" to the server. If you don't know exactly what you're looking for, or exactly where it is, there are programs and servers that can help you. For more info, send e-mail to mail-server@rtfm.mit.with with the body of the message reading send usenet/news.answers/finding-sources Thanks to Aliza R. Panitz (the "buglady") for this text. I copied it verbatim from her post on faq-maintainers with only minor modifications. = ====================================================================== * Acknowledgements ------------------ This document would not have happened without the help of many people. Among them are Marcus Speh, George Greenwade, Rob Beezer, Joachim Schrod, Piet van Oostrum, and Ross N. Williams. A special thanks to Aliza R. Panitz for the text describing how to execute an anonymous ftp for files of interest. Any omissions from these acknowledgements should be considered an act of stupidity on my part. Of course, the authors of literate programming tools mentioned above all play a vital role in the vitality of literate programming. Furthermore, participants in the comp.programming.literate newsgroup (and associated mailing list) all contributed in various fashions. Thank all of you. = ====================================================================== * End notes ----------- This document will continue to evolve. I'm planning on adding entries for additional literate programming tools and will expand the sections on examples as more examples become available. Tools I will include are WEB (the original pascal version) for starters. Others will be added as I find and document them. Omission of a particular tool should not be considered a snub in any sense--simply an error or oversight on my part. = End of File ========================================================== ================================================================================ Archive-Date: Sun, 16 Oct 1994 13:58:56 CDT Sender: owner-litprog@SHSU.edu From: viola@hlrz16 (Joerg Viola ) Reply-To: LitProg@SHSU.edu, viola@HLRZ16 Subject: Noweb TeX output Message-ID: Date: 15 Oct 94 19:29:29 GMT To: LitProg@SHSU.EDU Hello, a question concerning the documentation output formatting of noweb: It appears to me that sometimes, at the start of a documentation chunk, a new page is started, even if the old one is not nearly full. This results in pages containing only some lines of docs and some of code and 80 % emptiness. What to do ? joerg -- Joerg Viola | email: j.viola@kfa-juelich.de 0049 241 807060 | talk: viola@hlrz16.hlrz.kfa-juelich.de 0049 241 81099 | finger: viola@hlrserv.hlrz.kfa-juelich.de -- Joerg Viola | email: j.viola@kfa-juelich.de 0049 241 807060 | talk: viola@hlrz16.hlrz.kfa-juelich.de 0049 241 81099 | finger: viola@hlrserv.hlrz.kfa-juelich.de ================================================================================ Archive-Date: Sun, 16 Oct 1994 17:27:50 CDT Sender: owner-litprog@SHSU.edu From: norman@flaubert.bellcore.com (Norman Ramsey) Reply-To: LitProg@SHSU.edu, norman@FLAUBERT.BELLCORE.COM Subject: Re: Noweb TeX output Date: 16 Oct 1994 03:53:11 GMT Message-ID: <37q837$sf8@lowell.bellcore.com> CC: Joerg Viola To: LitProg@SHSU.EDU In article , Joerg Viola wrote: >a question concerning the documentation output formatting >of noweb: It appears to me that sometimes, at the start >of a documentation chunk, a new page is started, even if >the old one is not nearly full. This results in pages >containing only some lines of docs and some of code and >80 % emptiness. This ugly behavior is the result of an unpleasant compromise. I decided that at all costs, code chunks should fit on one page. Therefore, there is a \filbreak in the definitions of \nwendcode and \nwdocspar. Changing these definitions may give results you like better, at the cost of breaking code chunks across pages. See tex/support.nw in the noweb distribution for more info. Norman ================================================================================ Archive-Date: Sun, 16 Oct 1994 19:55:12 CDT Sender: owner-litprog@SHSU.edu From: trashy@icicle.winternet.com Reply-To: LitProg@SHSU.edu, trashy@ICICLE.WINTERNET.COM Date: 14 Oct 94 17:07 GMT+0300 Subject: Re: not-small C program with noweb. tho Message-ID: <37m3bq$bfe@blackice.winternet.co> To: LitProg@SHSU.EDU Subject: Re: not-small C program with noweb. thoughts? In article <37gj0h$pv1@paladin.american.edu> eric@american.edu (Eric Prestemon) writes: ]Are there examples of finished C/noweb programs out there, beyond what ]is in the noweb distribution? Specifically, I am interested in how ]people write functions and function calls cleanly (rather than inlining ]a chunk, which seems the more natural *WEB way to do things). I haven't yet written any large programs with noweb, but even in small programs I don't depend too much on the chunk mechanism, unless the language makes subroutines ungainly. (Perl may exhibit this property.) I like to put C subprograms in two main chunks. First I present a prototype, and then the definition, adjacent to each other. The prototype goes into a chunk that gets tangled to near the top of the C file, and (in a multiple-file program) to a header file. The definition can go almost anywhere in the C file. Some languages are much easier to handle. In Icon, for instance, globals can go anywhere, and there's no need for prototypes or the like. This works out very well; you can just put all globals in the root chunk, or wherever you like. ](As an aside, I'm not much of DOS guru, and the dosnoweb-2.5a ]distribution didn't include a cpif, as far as I can tell. I have written a cpif in C/noweb, for MS-DOS, but it hasn't been released yet. However, there is nothing outlandish about the code; all I did was duplicate the functions of the shell script. -- Barry Schwartz at MedGraphics trashy@winternet.com ================================================================================ Archive-Date: Sun, 16 Oct 1994 19:55:45 CDT Sender: owner-litprog@SHSU.edu From: thompson@sun1.coe.ttu.edu Reply-To: LitProg@SHSU.edu, thompson@SUN1.COE.TTU.EDU Date: 15 Oct 94 18:32 GMT+0300 Subject: comp.programming.literate FAQ Message-ID: <1636671105@literate-programming-faq_7822351> To: LitProg@SHSU.EDU Archive-name: literate-programming-faq Last-modified: 1994/08/23 Version: 1.1.10 Welcome to the Literate Programming Frequently Asked Questions List ------------------------------------------------------------------- This version was created Tuesday, August 23, 1994, and should considered stale after 90 days. Information contained in this document is the best available at preparation. The original file was dated October 15, 1993 (just for historical purposes). Disclaimer: "This FAQ is presented with no warranties or guarantees of ANY KIND including correctness or fitness for any particular purpose. The author of this document has attempted to verify correctness of the data contained herein; however, slip-ups can and do happen. If you use this data, you do so at your own risk." Copyright 1993, 1994 David B. Thompson. All rights reserved worldwide. Permission is granted to copy this document for free distribution so long as it remains intact and unmodified. For other arrangements, contact the author/maintainer via email: thompson@sun1.coe.ttu.edu. What's New? ----------- + Add Fold2Web entry. + Correct noweb.el entry. (Thanks Dominique!) + Update nuweb.el entry. + Update SchemeWEB entry. + Update WWW and literate programming entry. + Update c2cweb entry. = ====================================================================== * Introduction or "What's this all about?" ------------------------------------------ This document is for new and experienced users of literate programming tools. The purpose is to explain the concept of literate programming and to provide a resource for locating files of interest to literate programmers and those interested in literate programming. The Literate Programming (LitProg) Frequently Asked Questions (FAQ) list is maintained by Dave Thompson, who can be reached at: thompson@sun1.coe.ttu.edu * Preferred mailing address for FAQ related comments/questions. wqdbt@ttacs1.ttu.edu * Forwarded to my pc. Comment and constructive criticism is welcome. Direct flames to /dev/null (or > nul if you're a msdos user! ;-) If you find an error, please report it. I'm particularly interested in establishing the locations of generally available literate programming tools. If you are the author of such a tool and wish to have it included in this list, please send email. Please note this is a work-in-progress. It is *not* complete, and probably will not be complete for some months. Nevertheless, the information contained herein may be useful to some. Use it as it is intended. - ---------------------------------------------------------------------- - Typography ------------ Major sections of the FAQ are divided by double lines (====). Minor sections and other divisions are separated by single lines (----). Major topics use a "* " as a leader. Minor topics use a "- " as a leader. This should simplify searching for topics. = ====================================================================== Table of Contents: ------------------ * Introduction, or "What's this all about?" - Typography * How do I get the FAQ? - Literate Programming FAQ - FWEB FAQ * Is there a newsgroup? (The comp.programming.literate newsgroup) * What internet nodes are of interest to literate programmers? * What is literate programming? * How do I begin literate programming? * What literate programming tools are available and where are they? - APLWEB - AWEB - CLiP - CWEB - FunnelWeb - FWEB - IMPACT - lit2x - Literate Programmer's Workshop (LPW) - MapleWEB - MWEB (Schrod/Detig) - MWEB (Sewell) - noweb - nuweb - ProTeX - RWEB - SchemeWEB - Spidery WEB - WEB - WinWordWEB * Are there other tools I should know about? - C2LaTeX - c2cweb - c2man - cnoweb - Fold2web - FunnelWeb mode - noweb.el - nuweb.el - TIE - Web mode * What other resources are available? - World Wide Web - TeX Resources - Virtual Coursework * Are there any code examples? - Examples included with developer's tools - Cameron Smith's KR-CWEB - Stanford GraphBase * Bibliographies. * How to anonymously ftp. * Acknowledgements. * End notes. = ====================================================================== * How do I get the FAQ? ----------------------- - Literate Programming FAQ -------------------------- You have many ways to get a current copy of this FAQ. One is to use anonymous ftp (if you don't know how, see a later section in this FAQ) to connect to one of the Comprehensive TeX Arvchive Network (CTAN) sites or the Literate Programming Archive and retrieve a copy of the file. Open an ftp connection to one of the CTAN sites and retrieve the file: help/LitProg-FAQ (For more information on CTAN and the literate programming archive, see the section below entitled "Internet Nodes of Interest to Literate Programmers.") An alternative is to use the fileserver at Sam Houston State University (SHSU). Send a message to FILESERV@SHSU.EDU and include in your message: SENDME LITPROG.FAQ The file server will forward a copy of the file to you via email. - ---------------------------------------------------------------------- - FWEB FAQ ---------- Marcus Speh maintains the FWEB FAQ. The current version number is 1.29. It can be retrieved in the same way as this FAQ; either by anonymous ftp or through the SHSU file server. On the SHSU server, the file name is FAQ.FWEB. Invoke your ftp software, open a connection to NIORD.SHSU.EDU [192.92.115.8], attach to the directory FAQ, and transfer the file FAQ.FWEB. Alternatively, send a message to the file server, FILESERV@SHSU.EDU, and include the following text in a one line message: SENDME FAQ.FWEB The file server will send the current version of the file via email. The FWEB FAQ exists in various formats, including HyperText (see other resources below). In Europe, the complete distribution can also be obtained from ftp.desy.de [131.169.10.115] in directory /pub/faq/web/fweb/. It is also available from the literate programming archive (LPA) in the directory LPA/Documentation/faq/fweb (see the references to LPA below for more information). Also, Marcus Speh is looking for someone willing to take over the FWEB FAQ. The text of his email message follows... "Please add to the FWEB FAQ the note that I am looking for someone to take the maintenance of the FAQ over - I am ready to assist in any way whatsoever, including tons of mail, notes for v1.29->v1.30, Texinfo sources, a WWW server and Hypertextification etc." If you're interested, send mail to marcus@x4u2.desy.de and express your willingness to serve. = ====================================================================== * Is there a newsgroup? ----------------------- One of the most important resources is the literate programming newsgroup, comp.programming.literate. You can read this newsgroup using your standard reader. Altenatively, the newsgroup is gated to a mailing list hosted by George Greenwade and Sam Houston State University. You can subscribe by sending mail to the list-server, LISTSERV@SHSU.EDU, and include in the message one line of text: SUBSCRIBE LITPROG "your name in quotes" The list is unmoderated; messages sent to litprog@shsu.edu are automatically distributed to all subscribers and cross-posted to comp.programming.literate. Archives of the mailing list and newsgroup are maintained on niord.shsu.edu [192.92.115.8] in the directory litprog. = ====================================================================== * What internet nodes are of interest to literate programmers? -------------------------------------------------------------- The principal nodes of interest to literate programmers are the Literate Programming Archive (LPA hereafter) and the CTAN (Comprehensive TeX Archive Network). The Literate Programming Archive (LPA) is: Node: ftp.th-darmstadt.de [130.83.55.75] Directory: programming/literate-programming Notes: Fastest response during off-U.S. [yep] business hours. The CTAN sites are: ftp host IP CTAN root Institution and Sponsor ------------------------------------------------------------------------- ftp.tex.ac.uk 134.151.79.32 pub/archive Aston Univ./UK TeX U.G. ftp.dante.de 129.206.100.192 soft/tex DANTE e.V. ftp.shsu.edu 192.92.115.10 tex-archive Sam Houston State Univ. Other nodes and directories of interest include: Node: niord.shsu.edu [192.92.115.8] Directory: various (do some snooping!) Notes: Has a gopher server. Node: ftp.desy.de [131.169.10.115] Directory: pub/web. Various documents, samples, and the FWEB FAQ. Notes: Has a www server, http://info.desy.de:80/ = ====================================================================== * What is Literate Programming? ------------------------------- Literate programming is the combination of documentation and source together in a fashion suited for reading by human beings. In fact, literate programs should be enjoyable reading, even inviting! (Sorry Bob, I couldn't resist!) In general, literate programs combine source and documentation in a single file. Literate programming tools then parse the file to produce either readable documentation or compilable source. The WEB style of literate programming was created by D.E. Knuth during the development of his TeX typsetting software. All the original work revolves around a particular literate programming tool called WEB. Knuth says: The philosophy behind WEB is that an experienced system programmer, who wants to provide the best possible documentation of his or her software products, needs two things simultaneously: a language like TeX for formatting, and a language like C for programming. Neither type of language can provide the best documentation by itself; but when both are appropriately combined, we obtain a system that is much more useful than either language separately. The structure of a software program may be thought of as a web that is made up of many interconnected pieces. To document such a program we want to explain each individual part of the web and how it relates to its neighbours. The typographic tools provided by TeX give us an opportunity to explain the local structure of each part by making that structure visible, and the programming tools provided by languages such as C or Fortran make it possible for us to specify the algorithms formally and unambigously. By combining the two, we can develop a style of programming that maximizes our ability to perceive the structure of a complex piece of software, and at the same time the documented programs can be mechanically translated into a working software system that matches the documentation. Another author (Eric W. van Ammers) wrote me a short article treating his opinions on literate programming. The text follows: First observation on LP About 90% of the disussion on this list is about problems with applying some WEB-family member to a particular programming language or a special documentation situation. This is ridiculous, I think. Let me explain shortly why... Lemma 1: I have proposed for many years that programming has nothing to do with programming langauges, i.e. a good programmer makes good programs in any language (given some time to learn the syntax) and a bad programmer will never make a good program, no matter the language he uses (today many people share this view, fortunately). Lemma 2: Literate Programming has (in a certain way not yet completely understood) to do with essential aspects of programming. Conclusion 1: A LP-tool should be independent of programming language. Lemma 3: It seems likely that the so called BOOK FORMAT PARADIGM [ref. 1] plays an important role in making literate programs work. Lemma 4: There are very many documentation systems currently being used to produce documents in the BOOK FORMAT. Conclusion 2: A LP-tool should be independent of the documentation system that the program author whishes to use. My remark some time ago that we should discuss the generic properties of an LP-tool was based on the above observation. References: [1] Paul W. Oman and Curtus Cook. Typographical style is more than cosmetic. CACM 33, 5, 506-520 (May 1990) Second observation on LP The idea of a literate program as a text book should be extendend even further. I would like to see a literate program as an (in)formal argument of the correctness of the program. Thus a literate program should be like a textbook on mathematicics. A mathematical textbook explains a theory in terms of lemma and theorems. But the proofs are never formal in the sense that they are obtaind by symbol manipulation of a proof checker. Rather the proofs are by so called "informal rigour", i.e. by very precise and unambiguous sentences in a natural language. Eric W. van Ammers Department of Computer Science Wageningen Agricultural University Dreijenplein 2 E-mail: ammers@rcl.wau.nl 6703 HB Wageningen voice: +31 (0)8370 83356/84154 The Netherlands fax: +31 (0)8370 84731 = ====================================================================== * How do I begin literate programming? -------------------------------------- A recommended book is D.E. Knuth's collection of articles (1992) "Literate Programming," Center for the Study of Language and Information, Stanford University, ISBN 0-937073-80-6 (pbk). This book gives insight into Knuth's thoughts as he developed the web system of literate programming (and TeX for typesetting). It does not document methods for literate programming. A recommended book is Wayne Sewell's (1989) "Weaving a Program: Literate Programming in WEB," Van Nostrand Reinhold, ISBN 0-442-31946-0 (pbk). This book focuses on using Knuth's web system. Some talk exists in the newsgroup/mailing list for a Usenet University course in literate programming. I'm sure discussion of this topic will be welcomed. If you are interested, please participate. = ====================================================================== * What literate programming tools are available and where are they? ------------------------------------------------------------------- A significant number of tools for literate programming are available. Most have been ported from their original systems, so support multiple computer platforms. If you are the developer of such a tool, and would like to make the software freely available, please send me email and I'll reply with a form (like those below) for you to fill in. (Or short-circuit the process and kludge a form from below. :-) - ---------------------------------------------------------------------- - APLWEB -------- Developer: Christoph von Basum Version: Unknown Hardware: MSDOS Languages: IBM APL2 and STSC APL Formatter: Plain TeX Availability: Anonymous ftp from: LPA:/apl watserv1.uwaterloo.ca:/languages/apl/aplweb Readme: Unknown Description: None available. Support: Unknown Note: The status of this particular package is unknown. - ---------------------------------------------------------------------- - AWEB ------ Developer: Unknown Version: Unknown Hardware: Unknown Languages: Ada Formatter: Unknown Availability: Anonymous ftp from: LPA:/ada/web Readme: Unknown Description: None available Support: Not supported. - ---------------------------------------------------------------------- - CLiP ------ Developer: E.W. van Ammers and M.R. Kramer Version: Unknown Hardware: Vax/VMS, Unix, and MS-DOS Languages: Any programming language. Formatter: Any formatter (TeX, LaTeX, Troff, Runoff, etc) or any wordprocessor including WYSIWYG systems (Word Perfect, Win Word, Ami Pro, Word, etc.) Availability: Anonymous ftp from: sun01.info.wau.nl:/CLIP/ms_dos MS-DOS version sun01.info.wau.nl:/CLIP/vax_vms VAX/VMS version CTAN:/web/clip LPA:/machines/ms-dos LPA:/machines/vax Readme: With bundle above Description: CLiP does not use explicite commands to perform the extraction process. Rather it recognizes pseudostatemens written as comments in the programming language in question. CLiP distinguishes pseudostatments from ordinary comments because the former comply with a a particular style. This style can be adjusted to suit virtually any programming language. The CLiP approach to LP makes the system extremely versatile. It is independent of programming language and text processing environment. We designed CLiP to be compatible with hypertext systems as well but we have not yet experimented with this form of documentation. Features: + CLiP imposes virtually no limitations on the text-processing system used to produce the documentation. If the text-processor supports these items you can + structure the documentation according to your own taste. + include drawings, pictures, tables etc. + disclose your documentatio my means of X-ref tables, Indexes, Table of contents, Table of tables, Table of figures, etc. + typeset the documented code. + Extracts any number of modules from a maximum of 64 source files. + No pretty-printing. Code from the source files is copied "as is" to the module. + Appearance of code segments in the documentation matches those of the modules to ease the identification of code segements. + Supports partially specified data types. + Comprehensive user manual (preliminary version) and technical description. - No automatic generation of a X-ref table for program identifiers. Support: Bugs, problems and assistance by e-mail: ammers@rcl.wau.nl - ---------------------------------------------------------------------- - CWEB ------ Developer: Silvio Levy and D.E. Knuth Version: 3.0 Hardware: Unix systems (dos and amiga ports available) Languages: C and C++ Formatter: Plain TeX and LaTeX. Availability: Anonymous ftp from: labrea.stanford.edu:/pub/cweb LPA:/c.c++ CTAN:/web/c_cpp/cweb DOS version in CTAN:/web/c_cpp/cwb30p8c DOS version in LPA:/machines/ms-dos Amiga version CTAN:/web/c_cpp/AmigaCWEB Mac port of CTANGLE in LPA:/machines/mac LaTeX support in LPA:/c.c++ Readme: Bundled with above Description: No description provided. Support: Bugs to levy@math.berkeley.edu Note: A fork of CWEB 3.x was developed by Marc van Leeuwen which implements several changes to CWEB. It is available for anonymous ftp from ftp.cwi.nl:pub/cweb. The principle changes are: - Scans include files for typedef definitions - Grammar and formatting rules are well separated, allowing for run-time selection of a rule set (via command line option) - New manual. - ---------------------------------------------------------------------- - FunnelWeb ----------- Developer: Ross N. Williams: ross@guest.adelaide.edu.au Version: Unknown Hardware: MSDOS, Mac, VMS, Sun. Other ports reported. Languages: No restrictions. Formatter: Plain TeX for printing. Otherwise, no restrictions. Availability: Anonymous ftp from: CTAN:/web/funnelweb LPA:/independent ftp.adelaide.edu.au:/pub/funnelweb Readme: With bundle above. Description: FunnelWeb is a production-quality literate-programming tool that emphasises simplicity and reliability. Everything about FunnelWeb, from the simplicity of its language to the comprehensive tutorial in the user's manual, has been designed to make this as simple, as practical, and as usable a tool as possible. Features: + Provides a simple macro preprocessor facility. + Can produce typeset documentation. + Runs on Sun, VMS VAX, Macintosh, PC, and others. + Portable C source code distributed under GNU licence. + Comprehensive user's manual including tutorial. + Programming-language independent. + Can generate multiple output files. + Allows complete control over the output text. + Regression test suite with over 200 tests. + Fully worked example (in /pub/funnelweb/examples). - Requires TeX to produce typeset documentation. - Typesets program code using TT font only. Support: No formal support available. Mailing list maintained with about 50 subscribers. Informal assistance available from mailing list. - ---------------------------------------------------------------------- - FWEB ------ Developer: John A. Krommes Version: 1.30a (1.40 for the experienced, patient, and brave) Hardware: Unix, VMS, and DOS platforms (anything with ANSI C) Languages: C, C++, Fortran-77, Fortran-90, Ratfor, TeX; also, a language-independent mode. Formatter: Plain TeX and LaTeX. Availability: Anonymous ftp from: ftp.pppl.gov:/pub/fweb CTAN:/web/fweb LPA:/fweb DOS version in LPA:/machines/ms-dos Readme: In bundle with above. Description: It also has a well-developed user's manual and its own FAQ (see above). Beginning with 1.40, documentation is maintained in gnu texinfo format. It runs on most platforms: VMS, PC, UNIX, and pretty much anything that the GNU C compiler (GCC) is supported for. Features: + Processes multiple languages during a single run (so one can mix C and Fortran, for example). + Language-independent mode (v1.40). + Ability to turn off pretty-printing (v1.40). + Built-in Ratfor translator. + Built-in macro preprocessor (closely follows ANSI C, with extensions). + A style file that allows the user to adjust many parameters and behavior patterns of FWEB. + Various operator-overloading features that provide additional pretty-printing capabilities to languages such as C++ and Fortran-90. + Numerous miscellaneous features and command-line options. Support: Bug reports and suggestions to krommes@princeton.edu - ---------------------------------------------------------------------- - IMPACT -------- Developer: Timothy Larkin, from Levy/Knuth CWEB 3.1 Version: 1.0 Hardware: Macintosh; requires AppleEvents. Languages: C, C++ Formatter: TeX Availability: CTAN archives Readme: A short readme file is included in the SEA archive. Description: IMPACT implements CTangle from the Levy/Knuth CWEB 3.1. It operates as a foreground program, tangling files selected from the Mac File Picker. Or it can operate in the background, tangling files in response to odoc events sent by other applications, such as editors. Support: I welcome any reports of bugs. The product will be updated as new versions of the CWEB appear. Other features may be added as users suggest them. - ---------------------------------------------------------------------- - lit2x ------- Developer: Unknown Version: Unknown Hardware: Unknown Languages: Unknown Formatter: Unknown Availability: Anonymous ftp from: LPA:/independent Readme: Unknown Description: None available Support: Unknown - ---------------------------------------------------------------------- - Literate Programmer's Workshop (LPW) -------------------------------------- Developer: Norbert Lindenberg Version: 1.1 Hardware: Apple Macintosh Languages: C++, Object Pascal & others Formatter: self-contained WYSIWYG system Availability: Anonymous ftp from: LPA:/machines/mac CTAN:/web/lpw ftp.apple.com:/pub/literate.prog Readme: With bundle above. Also comes with 38-page manual. Description: The Literate Programming Workshop is an environment for the integrated development of program source text and documentation in combined documents. It consists of a WYSIWYG word processor based on a style sheet approach, a mechanism to extract parts of the text in a document, and a project management system that handles multi-document projects. The system is designed to be used in conjunction with the Macintosh Programmer's Workshop: it prepares raw source text for the MPW compilers, accepts MPW error messages, and shows them in the context of the original documents. Automatic indexing and hypertext features allow for easy access to both source text and documentation. LPW is shareware. Support: Bugs, problems, and questions to lpw@aol.com. - ---------------------------------------------------------------------- - MapleWEB ---------- Developer: Unknown Version: Unknown Hardware: Unknown Languages: Maple Formatter: Unknown Availability: Anonymous ftp from: LPA:/maple Readme: Unknown Description: None Support: Unknown - ---------------------------------------------------------------------- - MWEB (Schrod/Detig) --------------------- Developer: Joachim Schrod Version: Unknown Hardware: Unknown Languages: Modula-2 Formatter: Unknown Availability: Anonymous ftp from: LPA:/modula-2 Readme: Unknown Description: None Support: Not supported. - ---------------------------------------------------------------------- - MWEB (Sewell) --------------- Developer: Sewell Version: Unknown Hardware: Unknown Languages: Modula-2 Formatter: Unknown Availability: Anonymous ftp from: LPA:/modula-2 Readme: Unknown Description: None Support: Not supported. - ---------------------------------------------------------------------- - noweb ------- Developer: Norman Ramsey Version: 2.6 Hardware: Unix and DOS platforms. Languages: All programming languages. Formatter: Plain TeX, LaTeX, and HTML (Mosaic) formatters. Availability: Anonymous ftp from: CTAN:/web/noweb LPA:/independent DOS version also in LPA:/machines/ms-dos also bart.kean.edu:/pub/leew Last recourse, use bellcore.com:/pub/norman Readme: With bundle above. Description: noweb is designed to meet the needs of literate programmers while remaining as simple as possible. Its primary advantages are simplicity, extensibility, and language-independence. noweb uses 5 control sequences to WEB's 27. noweb now supports indexing and identifier cross-reference, including hypertext ``hot links'' courtesy of Mosaic. The simple noweb manual is only 2 pages; documenting the full power of noweave and notangle requires another 3 pages. noweb works ``out of the box'' with any programming language, and its formatter-dependent part is a 60-line nawk program. The primary sacrifice relative to WEB is the loss of prettyprinting. Support: email to the author - ---------------------------------------------------------------------- - nuweb ------- Developer: Preston Briggs: preston@cs.rice.edu Version: 0.87 Hardware: Unix systems: Sparcs, RS/6000s, HPs; (!) MSDOS and Amiga. Languages: Any programming language or combination of programming languages. Formatter: Latex Availability: Anonymous ftp from: Unix: CTAN:/web/nuweb DOS: CTAN:/web/nuweb-pc LPA:/independent Amiga: CTAN:/web/nuweb/nuweb_ami Amiga: wuarchive.wustl.edu/pub/aminet Readme: Send mail to preston@cs.rice.edu Description: A single program that takes a web file written in a combination of latex and any programming language(s) and produces a latex file that can be pretty printed and a set of files containing code for compilation/interpretation by the appropriate language processors. Strengths include speed, simplicity, multiple languages, nice indices and cross-references, latex. Doesn't require any special macros or macro files. Drawbacks: latex-dependent, no code pretty printing, harder to make indices than cweb. More good stuff: nice support for make, doesn't reformat source files, so they're easy to debug. Lots of control without too much effort. That is, it doesn't do too much! Future directions... Very little change planned, except perhaps refinements in the indexing software. Support: Hack it yourself or send e-mail to preston@cs.rice.edu - ---------------------------------------------------------------------- - ProTeX -------- Developer: Eitan Gurari Version: 1.1 (AlProTeX 1.2) Hardware: Any platform with TeX (ProTeX is written in TeX) Languages: Any language Formatter: TeX and LaTeX Availability: Anonymous ftp from: ftp.cis.ohio-state.edu : pub/tex/osu/gurari/ LPA:/independent Readme: Unknown Description: There is a book published on using ProTeX, @Book{Gurari:TLD94, author = "Eitan M. Gurari", title = "{\TeX} and {\LaTeX}: Drawing and Literate Programming", publisher = pub-MH, year = "1994", address = pub-MH:adr, bibdate = "Wed Sep 29 17:55:14 1993", acknowledgement = ack-nhfb, } Support: gurari@cis.ohio-state.edu - ---------------------------------------------------------------------- - RWEB ------ Developer: Unknown Version: Unknown Hardware: Unknown Languages: Unknown Formatter: Unknown Availability: Anonymous ftp from: LPA:/reduce Readme: Unknown Description: Web generator in AWK. Support: Unknown - ---------------------------------------------------------------------- - SchemeWEB ----------- Developer: John D. Ramsdell Version: 2.1 Hardware: Unix and DOS platforms Languages: Any dialect of Lisp. Formatter: LaTeX. Availability: The Unix version is in the Scheme Repository and it is available via anonymous ftp from: cs.indiana.edu:/pub/scheme-repository/utl/schemeweb.sh LPA:/lisp CTAN:/tex-archive/web/schemeweb The DOS version is part of the PCS/Geneva Scheme system which is available via anonymous ftp from: cui.unige.ch:/pub/pcs LPA:/machines/ms-dos Readme: In bundle with above. Description: SchemeWEB is a Unix filter that allows you to generate both Lisp and LaTeX code from one source file. The generated LaTeX code formats Lisp programs in typewriter font obeying the spacing in the source file. Comments can include arbitrary LaTeX commands. SchemeWEB was originally developed for the Scheme dialect of Lisp, but it can easily be used with most other dialects. Support: Bug reports to ramsdell@mitre.org. - ---------------------------------------------------------------------- - SpideryWEB ------------ Developer: Norman Ramsey Version: Unknown Hardware: Unix and DOS platforms Languages: Most Algol-like languages, including C, Ada, Pascal, Awk, and many others. Formatter: Plain TeX and latex for text formatters. Availability: Anonymous ftp from: CTAN LPA:/spiderweb Readme: In distribution. Description: A system for building language-dependent WEBs. Spider is frozen; no further development is planned. Support: Bug reports to spider-bugs@oracorp.com. - ---------------------------------------------------------------------- - WEB ----- Developer: Donald Knuth Version: Unknown Hardware: Unknown Languages: Pascal Formatter: TeX (of course! ;-) Availability: Anonymous ftp from: LPA:/pascal Readme: Unknown Description: This is the original software that started it all. The original TeX processor was written in WEB. Support: None known. - ---------------------------------------------------------------------- - WinWordWEB ------------ Developer: Lee Wittenberg Version: Unknown Hardware: Needs Microsoft Word for Windows, v.2.x, and, of course, MS-Windows 3.x. Languages: Any programming language. Formatter: Word for Windows 2.x for text formatting and file maintenance. Availability: Anonymous ftp from: bart.kean.edu:pub/leew LPA:/machines/ms-dos World-Wide Web (WWW) Readme: WORDWEB.DOC in the downloadable package describes the system. Description: WinWordWEB is a set of a Word for Windows macros (plus a paragraph style) that provide a crude literate programming environment. The ``look and feel'' of the system is based on Norman Ramsey's noweb, but can easily be modified to suit individual tastes. Support: None. WinWordWEB was written as a prototype to see if a WYSIWYG literate programming system was possible. It is intended as a jumping off point for future work by others. However, the system is surprisingly usable as it stands, and the author is interested in hearing from users (satisfied and dissatisfied). Anyone interested in actively supporting (and improving) the product should contact the author via email. = ====================================================================== * Are there other tools I should know about? -------------------------------------------- First of all, I'll list some not-quite-literate-programming tools. Some may consider these to be pretty-printers. Others may call them literate programming tools. In any event, they don't seem to be quite in the same category as the tools listed above, so I'll include them here. - C2LaTeX --------- Developer: John D. Ramsdell Version: Unknown Hardware: Unix Languages: C Formatter: LaTeX but it's easy to change the formatter. Availability: Anonymous ftp from omnigate.clarkson.edu:/pub/tex/tex-programs/c2latex. Readme: Absent. Documentation is in the C source for c2latex. Description: C2latex provides simple support for literate programming in C. Given a C source file in which the comments have been written in LaTeX, c2latex converts the C source file into a LaTeX source file. It can be used to produce typeset listings of C programs and/or documentation associated with the program. C2latex produces LaTeX source by implementing a small number of rules. A C comment that starts at the beginning of a line is copied unmodified into the LaTeX source file. Otherwise, non-blank lines are surrounded by a pair of formatting commands (\begin{flushleft} and \end{flushleft}), and the lines are separated by \\*. Each non-blank line is formatted using LaTeX's \verb command, except comments within the line are formatted in an \mbox. Support: Send bug reports to ramsdell@mitre.org. - ---------------------------------------------------------------------- - c2cweb -------- Developer: Werner Lemberg Version: 1.4 Hardware: DOS, OS/2, Unix (gcc) - CWEB source included Languages: C, C++ Formatter: TeX Availability: Anonymous ftp from CTAN:/web/c_cpp/c2cweb Readme: In distribution. Description: c2cweb will transform plain C or C++ code into a CWEB file to get a pretty formatted output. A modified CWEAVE (which transforms the CWEB file into a TeX file, see below) is included also. Support: Werner Lemberg - ---------------------------------------------------------------------- - c2man ------- Developer: Graham Stoney Version: 2.0 patchlevel 26 Hardware: Unix, MSDOS, OS/2. Languages: C Formatter: nroff -man, texinfo (requires yacc/byacc/bison, lex/flex, and nroff/groff/texinfo/LaTeX). Availability: Anonymous ftp from ftp.wustl.edu: /usenet/comp.sources.reviewed/volume03/c2man* ftp.informatik.uni-stuttgart.de: /pub/archive/comp.sources/reviewed/c2man* Readme: See distribution. Description: The primary philosophy here is to use the programming language as far as possible to express the programmer's intentions, and to use comments only when the programming language is not sufficiently expressive. A comment can then become part of the language grammar which is recognised by a "documentation compiler". This tool parses a superset of the programming language and can automatically generate documentation in human-readable form by associating the programmer's comments with the objects in the code by their context. Support: Actively supported; mailing list available: send "subscribe c2man " (in the message body) to listserv@research.canon.oz.au. - ---------------------------------------------------------------------- - cnoweb -------- Developer: Jim Fox Version: 1.4 (January 4, 1991) Hardware: Anything with C and TeX. Languages: C Formatter: Plain TeX. Availability: Anonymous ftp from: CTAN LPA:/c.c++ Readme: Unknown, cnoweb.tex contains documentation. Description: cnoweb is as it's name describes: write C, not web. No tangling or weaving is implemented. Documentation (between standard /* */ delimiteres) is written in TeX. cnoweb provides typesetting of documentation, an table of contents of routines, and pretty-printing of C source. Support: None known. - ---------------------------------------------------------------------- - Fold2Web ---------- Developer: Bernhard Lang Version: V0.8 Hardware: MSDOS Languages: All (must allow comment lines) Formatter: LaTeX Availability: Anonymous ftp from: kirk.ti1.tu-harburg.de (134.28.41.50) /pub/fold2web/readme /pub/fold2web/fold2web.zip Readme: In distribution Description: The idea behind the Fold2Web tool is the following: A programmer can write his program source with a folding editor and later map the folded source files automatically to WEB-files. The generated WEB-files can then be modified by inserting required documentations. The advantage by starting program developement with original sources is to get short design cycles during the compile/debug steps. By using a folding editor the global structuring information can be already captured in folds during this developement phase. Fold information is typically stored in comment lines and thus will not affect the efficiency of the compile/debug design cycle. Some folding editors and a folding mode for the emacs are available (e.g. see our FUE folding editor for MSDOS machines which is a modified micro emacs. Pick it at kirk in directory /pub/fold2web). After reaching a stable version of a program source its time to convert the source file to a WEB-file and do the program documentation. Fold2Web is written to convert folded source text of any programming language to nuweb files. The folded structure is kept by mapping folds to scraps. Fold markers which differ between languages due to different ways of specifying comments can be configured for each language. Good results can also achived when given but poor documented program sources have to be modified. Such sources can be folded using a folding editor to extract the global structures. This offers a global view to the program structures and help to understand its functionality. Furthermore the program code is not affected, only comment lines are inserted. Once folded the program source can be automatically translated to a WEB document using the above tool. Support: email to lang@tu-harburg.d400.de - ---------------------------------------------------------------------- - Funnelweb Mode ---------------- Developer: Daniel Simmons Version: Unknown Availability: Litprog archives (was in email) Anonymous ftp from: ftp.imada.ou.dk Description: The other day I did a quick hack to nuweb.el as included with the nuweb distribution so as to make a funnelweb-mode.el. I've only used it briefly, and I'm sure that it can be improved quite a bit. I've been thinking about adding support for folding on sections, a pull-down menu to select macro definitions (like the recent functions posted to gnu.emacs.sources for a C function definition pull-down menu) and some kind of tags support for funnelweb. Support: Unknown - ---------------------------------------------------------------------- - noweb.el ---------- Developer: Bruce Stephens Version: Unknown. Availability: LitProg archives (in an email message). Description: This is a very simple mode I just hacked up. There's a lot wrong with it, but I thought others may be interested, even as it stands. It *requires* text properties, and assumes those used in GNU Emacs 19.22; it'll quite likely work with Lucid Emacs, but I haven't tried it. I use it with auctex8.1 and cc-mode 3.229, both of which are loaded separately (I think my emacs is dumped with them, in fact). The idea is to have one mode (which calls itself c-mode, but actually has LaTeX-mode keybindings) generally (this means that the code is hilighted nicely), and have the code chunks use a different keymap. Support: Email to bruce@liverpool.ac.uk - ---------------------------------------------------------------------- - nuweb.el ---------- Developer: Dominique de Waleffe Version: 1.99 Availability: Anonymous ftp from: LPA CTAN Description: Provides a major mode extending Auctex for editing nuweb files. Main features (in 2.0): - Edit scrap bodies in a separate buffer in a different mode (selected using emacs defaults for files, specific indication -*-mode-*-, or a buffer-local variable) - Extends Auctex commands so that nuweb is called before LaTeX, - Easy navigation on scrap definition and use points. - Now creates an imenu (C-M-mouse1) with user index entries, macro definition positions and file definition positions. Support: Email to ddw@sunbim.be - ---------------------------------------------------------------------- - TIE ----- Developer: Unknown Version: Unknown Hardware: Unknown Availability: Anonymous ftp from: LPA:/Tools Readme: Unknown Description: This software merges change files. Support: Unknown - ---------------------------------------------------------------------- - Web mode ---------- Developer: Bart Childs Version: Unknown Tools supported: web, fweb, cweb, funnelweb Availability: Anonymous ftp from ftp.cs.tamu.edu:pub/tex-web/web/EMACS.web-mode thrain.anu.edu.au:pub/web/EMACS.web-mode Description: This version works with versions 18 and 19 of Emacs to be best of my knowledge. I have cleaned up a number of documentation items ... In the same directory is wm_refcard.tex which is an edited version of the famous one to include some web-mode commands. The files limbo* are related to its use and notice that half them have an uppercase L in them for LaTeX. The setup is based upon the fact that we (I am not alone here) primarily use FWEB for C and Fortran programming. We are using version 1.40 of FWEB although John Krommes warns that it is not mature and the manual is not yet updated. The info files are! We are using LaTeX almost exclusively. That will likely change and we will revert to version 1.30 if the final form of 1.40 cannot return to the simple section numbers and avoid the HORRIBLE LATEX 0.1.7.2.4.6 type section numbers. Support: Unknown = ====================================================================== * What other resources are available? ------------------------------------- - World Wide Web ---------------- An untapped resource (by me anyway ;-) is the World Wide Web. Marcus Speh has expended considerable effort in this regard. If you're connected to WWW, then access: http://info.desy.de:80/user/projects/LitProg.html If you aren't connected to WWW, telnet to info.cern.ch and explore. You can reach Marcus' literate programming pages by typing: go http://info.desy.de:80/user/projects/LitProg.html Help for people who have only Email and neither WWW nor telnet, can be obtained by Email from TEST-LIST@INFO.CERN.CH by sending a message, SEND , for example, SEND http://info.desy.de:80/user/projects/LitProg.html to retrieve the LitProg library page. A help file can be retrieved by sending a message to the list server above with the text HELP in the body of the message. Instructions will be returned by email. For literate programming documents, you can try anonymous ftp to ftp.desy.de [131.169.10.115] and get the file: /pub/userWWW/projects/Announce/LitProg.txt - ---------------------------------------------------------------------- - TeX Resources --------------- Another resource of interest to literate programmers is the info-tex mailing list. If you're using (La)TeX as your typsetting system and have access to internet, then you should investigate this mailing list. Mail list service is available through the SHSU list-server. To subscribe, send a message to LISTSERV@SHSU.EDU, and include in the message one line of text: SUBSCRIBE INFO-TEX "your name in quotes" The list is unmoderated; messages sent to info-tex@shsu.edu are automatically distributed to all subscribers and cross-posted to comp.text.tex. Archives of the mailing list and newsgroup are maintained on niord.shsu.edu [192.92.115.8] in the directory info-tex. Another reason the TeX resources should be important is that so many of the literate programming tools rely on either plain TeX or LaTeX as their text formatter. (La)TeX software systems exist for most computing platforms. These systems can be found on CTAN and other major archive sites. Use archie to find them or simply ftp to one of the CTAN sites and browse. - ---------------------------------------------------------------------- - Virtual Coursework -------------------- Marcus Speh plans an introductory course on Literate Programming on the Internet, part of the first semester of "Global Network Academy" [GNA], a non-profit corporation incorporated in the state of Texas, affilated with the Usenet University project. The texts/sample programs for this class will be made available via the World-Wide Web. A special room on GNA Virtual Campus will be staffed by a consultant in one to two hour shifts. Students with questions can telnet to the virtual campus and ask questions of the staff there. If you are interested in registering for the course either as a student or as a consultant, please contact marcus@x4u.desy.de. You will receive a standard reply message; no further action will be taken until June 94. Interested parties can check the hypertext notes for the completed C++ Course done in a similar fashion, at URL http://info.desy.de:80/pub/uu-gna/html/cc/index.html [Editor's note: Because of workload, Marcus requests that email inquiries be limited to a statement of interest for either a student or consultant position until June 1994.] = ====================================================================== * Are there any code examples? ------------------------------ Examples of web programs are included with the FWEB, CWEB, and noweb distributions. nuweb is written in itself. Cameron Smith converted the K&R calculator program into a literate program. It can be retrieved by anonymous ftp from: niord.shsu.edu [192.92.115.8] directory kr-cweb-sample as krcwsamp.zip or from LPA/Documentation Ross Williams has released a funnelweb example. You can retrieve this file from node ftp.adelaide.edu.au [129.127.40.3] as /pub/funnelweb/examples/except.* This file should be on CTAN as well. Lee Wittenberg has posted a few litprog examples. They are available via anonymous ftp from: bart.kean.edu:/pub/leew/samples.LP The Stanford GraphBase is a large collection of programs by Don Knuth for doing all kinds of computations and games with graphs; it is written in (Levy/Knuth) CWEB. More details in the distribution. It is available via anonymous ftp from: labrea.stanford.edu:/pub/sgb = ====================================================================== * Bibliographies ---------------- Nelson Beebe has collected an extensive bibliography treating literate programming. His work is available for anonymous ftp from ftp.math.utah.edu [128.110.198.2] in directory /pub/tex/bib as files: litprog.bib litprog.ltx litprog.twx. Although I have not verified this, LPA is an alternate source for these files. Note that they are updated frequently (Nelson says several times each week), so be sure to get a fresh copy before extensive use. Joachim Schrod indicates that these files may be updated daily and can be retrieved via anonymous ftp at LPA/documentation. = ====================================================================== * How to anonymously ftp ------------------------ Pretty much everything mentioned here is available by anonymous FTP. FAQ lists cross-posted to news.answers and rec.answers can be gotten from rtfm.mit.edu [18.181.0.24], under /pub/usenet/news.answers or under /pub/usenet/more.specific.group.name "anonymous FTP" is just a way for files to be stored where anyone can retrieve them over the Net. For example, to retrieve the latest version of the literate programming FAQ, do the following: > ftp rtfm.mit.edu /* connect to the site; message follows */ > anonymous /* type this when it asks for your name */ > /* type your address as the password */ > cd /pub/usenet /* go to the directory you want to be */ > cd comp.programming.literate /* one level down (no slash). */ > dir /* look at what's there */ > get literate-progamming-faq /* get the file; case-sensitive */ > quit /* stop this mysterious thing */ If your FTP program complains that it doesn't know where the site you want to use is, type the numerical address instead of the sitename: > ftp 18.181.0.24 /* connect with numerical address */ If you don't have ftp access, send e-mail to mail-server@rtfm.mit.edu with the single word "help" in the body of the message. Getting binary files (executables, or any compressed files) is only slightly more difficult. You need to set binary mode inside FTP before you transfer the file. > binary /* set binary transfer mode */ > ascii /* set back to text transfer mode */ FAQs and spoiler lists are generally ascii files; everything else is generally binary files. Some common extensions on binary files in archive sites are: .Z Compressed; extract with uncompress .tar.Z Compressed 'tape archive'; uncompress then untar or tar -xvf .gz or .z Gnu gzip; use gunzip (available from prep.gnu.ai.mit.edu) .sit (Mac) StufIt archive .zip Extract with Zip or Unzip .zoo Yet another archive/compress program .lhe (Amiga) ? .lzh Lha archive program. .arj (PC) Arj archive program. .exe (PC) Sometimes self-extracting archives-just execute them. .uue or .UUE Transfer as text file; use uudecode to convert to binary .hqx (Mac) BinHex format; transfer in text mode Generic help can be found in the FAQs of comp.binaries. for how to transfer, extract, and virus-check binary files. (At rtfm.mit.edu) If you can't FTP from your site, use one of the following ftp-by-mail servers: ftpmail@decwrl.dec.com ftpmail@src.doc.ic.ac.uk ftpmail@cs.uow.edu.au ftpmail@grasp.insa-lyon.fr For complete instructions, send a message reading "help" to the server. If you don't know exactly what you're looking for, or exactly where it is, there are programs and servers that can help you. For more info, send e-mail to mail-server@rtfm.mit.with with the body of the message reading send usenet/news.answers/finding-sources Thanks to Aliza R. Panitz (the "buglady") for this text. I copied it verbatim from her post on faq-maintainers with only minor modifications. = ====================================================================== * Acknowledgements ------------------ This document would not have happened without the help of many people. Among them are Marcus Speh, George Greenwade, Rob Beezer, Joachim Schrod, Piet van Oostrum, and Ross N. Williams. A special thanks to Aliza R. Panitz for the text describing how to execute an anonymous ftp for files of interest. Any omissions from these acknowledgements should be considered an act of stupidity on my part. Of course, the authors of literate programming tools mentioned above all play a vital role in the vitality of literate programming. Furthermore, participants in the comp.programming.literate newsgroup (and associated mailing list) all contributed in various fashions. Thank all of you. = ====================================================================== * End notes ----------- This document will continue to evolve. I'm planning on adding entries for additional literate programming tools and will expand the sections on examples as more examples become available. Tools I will include are WEB (the original pascal version) for starters. Others will be added as I find and document them. Omission of a particular tool should not be considered a snub in any sense--simply an error or oversight on my part. = End of File ========================================================== ================================================================================ Archive-Date: Mon, 17 Oct 1994 05:45:24 CDT Sender: owner-litprog@SHSU.edu From: schrod@iti.informatik.th-darmstadt.de (Joachim Schrod) Reply-To: LitProg@SHSU.edu, schrod@ITI.INFORMATIK.TH-DARMSTADT.DE Subject: Re: FWEB Date: 17 Oct 1994 10:35:24 GMT Message-ID: <37tk1c$13t0@rs18.hrz.th-darmstadt.de> To: LitProg@SHSU.EDU In article <1994Oct14.002653.6032@afterlife.ncsc.mil>, jsrobin@afterlife.ncsc.mil (John S. Robinson) writes: > >I won't elaborate on any problems with a `PRELIMINARY TEST RELEASE' > >of LaTeX2e that is known to have **many** bugs, some of them leading > >to obscure reactions. He should install the current version, try it > >again, and then come back if the error message still is there. > > Well Mr. Joachim, I have scotched one 11 hr work day installing and > verifying the latest greatest version of TeX, LaTeX2e, MakeTeXPK, > and xdvik. If you would have send me private email before, I would have told you that just installing a current LaTeX2e was what I meant with my paragraph above. In the version you were using there were known problems with the font handling, one doesn't want to check any font related problem as long as they're still there. > The end result thoroughly surprised me. The same error > occurs. fwebmac.web: Discard the section @ \FWEB\ now supports \LaTeX's NFSS (new font selection scheme). Macros courtesy of Charles Karney, Princeton U. @A \ifx\selectfont\undefined\else \fontsize{10}{12pt}\rm % The standard font for bulk of document. \fi At the time when this code is evaluated, \rm is not yet defined. Change the definition of \Wbegin to \def\Wbegin[#1]#2#3#4#5#6#7{\edef\contentsfile{#5}% \def\readcontents{\input\contentsfile}% \Wequate#6 \ifLaTeXisloaded >> \documentstyle[#1,12pt]{#2}% \textwidth\pagewidth \textheight\pageheight \TeXindent#3 \begin{document} \pageno=2 \else \TeXindent#3 \fi \notch#4 \output {\setbox0=\page% The first page is garbage \immediate\openout\cont=\contentsfile \global\output{\normaloutput\page\lheader\rheader}% }% % Here we print out a garbage page, so that the first |\topmark| won't be null. \setpage \vbox to \vsize{} } (I marked the changed line with `>>'.) Instead of this change one can also copy the macros that were deleted above down into the expansion of \Wbegin. \rm is defined by all standard classes, e.g., by article.cls which is the one used most often. That means, it's available after \documentstyle or \documentclass was evaluated. Joachim -- =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= Joachim Schrod Email: schrod@iti.informatik.th-darmstadt.de Computer Science Department Technical University of Darmstadt, Germany ================================================================================ Archive-Date: Mon, 17 Oct 1994 15:21:54 CDT Sender: owner-litprog@SHSU.edu From: theedge@rbg.informatik.th-darmstadt.de (felix gaertner) Reply-To: LitProg@SHSU.edu, theedge@RBG.INFORMATIK.TH-DARMSTADT.DE Subject: Style of header file inclusion Date: 17 Oct 1994 20:09:21 GMT Message-ID: <37ullh$12pg@rs18.hrz.th-darmstadt.de> To: LitProg@SHSU.EDU I'm currently going over some code I wrote a year ago and came across an interesting point concerning literate programming style. I am interested in how people write the inclusion of header files `literally'? (I am using CWEB, but that's not so important for the style.) A year ago I used to do this: ------- begin example 1----------------------------------------- @ This is the overview over the program. @c @ @ @ [later:] @ We've used the |foo| function so we need to include its header. @= #include"foo.h" ... ------ end example 1 -------------------------------------------- During the course of the program all #includes were added to this one module when it seemed suitable. But on the other hand, I also used this style, the point being that common headers were mentioned directly in the unnamed module, even if their use wasn't directly visible already. ------- begin example 2 ------------------------------------------ @ This is an overview... @c #include #include @ @ @ ... -------- end example 2 -------------------------------------------- I wonder how other people do this? It would also be interesting to know which names people give to the module that `collects' all the #includes? (e.g. ,
, etc.) I wonder if I have made my point clear? It's a simple stylistic issue, I believe. Cheers, Felix ================================================================================ Archive-Date: Mon, 17 Oct 1994 17:59:35 CDT Sender: owner-litprog@SHSU.edu From: matomira@di.epfl.ch (Fernando Mato Mira) Reply-To: LitProg@SHSU.edu, matomira@DI.EPFL.CH Subject: several docs from the same noweb file? Date: 17 Oct 1994 22:15:41 GMT Message-ID: <37ut2d$9vn@disunms.epfl.ch> MIME-Version: 1.0 Content-Type: text/plain; charset=iso-8859-1 Content-Transfer-Encoding: 8bit To: LitProg@SHSU.EDU Hello, Would anybody care to give a short example of how to write/use a noweb file to generate: 1. A reference manual (only function signatures / public slots of stuctures appear in the doc + some description + short example) 2. A user's guide (no signatures, presentation follows a different order, long examples). 3. An implementors' manual (like a refence manual, but with discussion about caveats, etc.). 4. A classic literate program doc (need not include the examples). I guess 2) should probably be written separately. By the way, is it possible to `include' pure documentation files into a noweb file? a. Editing a file with correct code just do document seems a bad idea. An error might be introduced accidentally. b. A documentation might be cleaned-up by someone not authorized to change the code. c. Touching the file with the code is uncool with make et al. d. Too much doc mixed with the code makes it unpractical for programming (unless non-code sections can be hidden in Emacs). PS: If what I want seems to point to some other system, please note that I program in Lisp. Thanks a lot, -- F.D. Mato Mira http://ligwww.epfl.ch/matomira.html Computer Graphics Lab matomira@epfl.ch EPFL FAX: +41 (21) 693-5328 ================================================================================ Archive-Date: Tue, 18 Oct 1994 07:13:45 CDT Sender: owner-litprog@SHSU.edu Date: Tue, 18 Oct 94 13:05:30 +0100 From: kaufmann@analog.shraero.co.at (Roland Kaufmann SCHRACK AEROSPACE) Reply-To: LitProg@SHSU.edu, kaufmann@ANALOG.SHRAERO.CO.AT Message-ID: <9410181205.AA00830@analog.co.at.> To: LitProg@SHSU.edu, theedge@rbg.informatik.th-darmstadt.de Subject: Re: Style of header file inclusion Hello all, in the hope that this is not too lengthy, some excerpts from a multi-file CWEB I have written some time ago. It was converted to ``literate'' form after writing in pure C (someone else wrote the code, I tried to make easier to understand for myself and hopefully others. Note that I use colons to indicated omitted parts of the file and meta-comments added for this posting starting with a double percent sign. -- drs-pp.w ------------------------------------------------------------ : : @ The programme layout. Literate programming allows to present the code in small pieces which makes it much easier to get an overview of a complex piece of software. The programme \.{\ProgramName} consists of several \Cee\ files: \medskip \halign{\indent#\hfil&\qquad#\hfil\cr \.{drs-pp.c} & |main()| and some auxiliary routines.\cr \.{config.h} & Machine and operating system dependencies.\cr \.{drs-pp.h} & Declaration of common objects.\cr \.{btb.c} & Handling of BOSS standard tabular files~[COM91,~section~I].\cr \.{memory.c} & Handling of multi-dimensional arrays.\cr \.{cubspl.c} & Cubic spline interpolation.\cr \.{process.c} & Computation of degradation and two-dimensional cuts.\cr \.{phnoise.c} & Computation of error rate with phase noise.\cr \.{math.c} & Numerical integration, special functions.\cr \.{mdfile.c} & Access to BOSS multi-dimensional files.\cr } % This has to be updated MANUALLY! \medskip which are produced from the corresponding \.{CWEB} sources \.{*.w}. The header files are treated differently---the declarations in \.{drs-pp.h} originate in the \.{CWEB} source where the objects (functions, variables) are defined. The ``master'' file \.{drs-pp.w} ensures that all the declarations are tangled into the file \.{drs-pp.h} where each \.{*.c} file can include it to allow separate compilation. On the other hand, the file \.{config.h} is standard \Cee\ and contains \Cee-preprocessor constants to adapt the programme to different environments. @ The file \.{drs-pp.c} contains the |main()| function and a few auxiliaries. In contrast to all other \Cee\ files, which use the ``file module'' construct of CWEB~[Lev90], this one will be tangled straight from the following ``unnamed module''. A warning message is inserted in a \Cee\ comment at the beginning of each file. Modifications should be done in the \.{CWEB} source or using the change file mechanism~[Lev90,Knu84,Knu89a] and not in the \Cee\ code! % the AT/ forces a line break % This is the only ``unnamed module''! @c @=/* This file (drs-pp.c) has been produced automatically from 'drs-pp.w'.@>@# @= You almost certainly shouldn't edit it! */@>@# @ @; @@; @ @; @@; @<|screen_output_main()| @>@; @<|screen_output_cut2d_1()| @>@; @<|screen_output_cut2d_2()| @>@; @ @; @ We need standard input and output, string functions and character classification from the \Cee\ library. Everything common to all \Cee\ files should be in \.{drs-pp.h}. @f const static @= #include #include #include #include "drs-pp.h" @ Global |#define|\thinspace s. As we have several \Cee\ files, we need to distribute definitions which should be visible in all modules via a header file which is |#include|\thinspace d by each \Cee\ file. @(drs-pp.h@>= @=/* This file (drs-pp.h) has been produced automatically from 'drs-pp.w'.@>@# @= You almost certainly shouldn't edit it! */@>@# #include "config.h" @@; @@# : @@; : %% Larger pieces are included from separate webs like this: @* Cubic Spline interpolation. @i cubspl.w : %% This is added to make this sort of self-consistent @* References. % For this short (?) document, ``hand made'' references are used---I % simply do not know how to make automatic references (like LaTeX's % \cite) in plain TeX. This is from the TeXbook, page 340 adapted to % my personal stylistic preferences. \medskip {\frenchspacing % put everything in a group to avoid % side effects \item{[COM91]} COMDISCO SYSTEMS,~INC. \hfil\break {\it Block Oriented Systems Simulator (BOSS) \hfil\break User's Guide} \hfil\break COMDISCO SYSTEMS, INC., BOS1080, Version 2.7, Jun.~1991 \hfil\break \item{[Lev90]} S.~Levy, D.~E.~Knuth \hfil\break {\it The {\tt CWEB} System of Structured Documentation} \hfil\break \TeX\ 3.14 Distribution \hfil\break \item{[Knu89a]} D.~E.~Knuth \hfil\break {\it The {\tt WEB} System of Structured Documentation} \hfil\break \TeX\ 3.14 Distribution \hfil\break \item{[Knu84]} D.~E.~Knuth \hfil\break {\it Literate Programming} \hfil\break The Computer Journal~{\bf 27:2}, 1984, pp.~97--111 \hfil\break } ------------------------------------------------------------------------ For those which are not tired (bored?) already, this is how 'cubspl.w' starts: -- cubspl.w ------------------------------------------------------------ @= @@; @@; @@; @@; @ The following constants are exported to all other \Cee\ translation units via \.{drs-pp.h}: @= #define NATURAL 1.e30 /* Use this for |yp1|, |ypn| to specify ``natural'' boundary conditions in |spline()|. */ #define MAX_INTPTS 100 /* Maximum number of points for interpolation. */ @ The file \.{cubspl.c} contains: @(cubspl.c@>= @=/* This file (cubspl.c) has been produced automatically from 'drs-pp.w'@>@# @= and 'cubspl.w'. You almost certainly shouldn't edit it! */@>@# @@; @@; : ------------------------------------------------------------------------ In the hope that this is useful (interesting), happy weaving Roland ========================================================================== Roland Kaufmann Tel.: +43 1 81100 5563 Systems Engineer Fax: +43 1 81100 5577 Studies Group e-mail: kaufmann@shraero.co.at Signal Processing SCHRACK Aerospace Breitenfurterstr. 106-108 A-1120 Vienna, AUSTRIA IEEE Member 8542359 ========================================================================== ================================================================================ Archive-Date: Tue, 18 Oct 1994 23:39:35 CDT Sender: owner-litprog@SHSU.edu From: jsrobin@afterlife.ncsc.mil (John S. Robinson) Reply-To: LitProg@SHSU.edu, jsrobin@AFTERLIFE.NCSC.MIL Subject: Re: FWEB Message-ID: <1994Oct19.010617.16107@afterlife.ncsc.mil> Date: Wed, 19 Oct 1994 01:06:17 GMT To: LitProg@SHSU.EDU In article <37tk1c$13t0@rs18.hrz.th-darmstadt.de>, Joachim Schrod wrote: (In order to use fweb in latex mode that one should:) >fwebmac.web: Discard the section > > @ \FWEB\ now supports \LaTeX's NFSS (new font selection scheme). Macros > courtesy of Charles Karney, Princeton U. > @A > \ifx\selectfont\undefined\else > \fontsize{10}{12pt}\rm % The standard font for bulk of document. > \fi > >At the time when this code is evaluated, \rm is not yet defined. > >Change the definition of \Wbegin to > > \def\Wbegin[#1]#2#3#4#5#6#7{\edef\contentsfile{#5}% > \def\readcontents{\input\contentsfile}% > \Wequate#6 > \ifLaTeXisloaded >>> \documentstyle[#1,12pt]{#2}% > \textwidth\pagewidth Thanks very much for help. The fix suggested works quite well on sparc 10 using FWEB 1.40 and applying the aforementioned changes to the fwebmacL.sty file instead of the fwebmac.sty file. I tried the same approach on a 486 running linix and got the result: //ValueAssignment/fweb 5821 > fweave testval.web This is FWEAVE [UNIX version 1.40 (October 30, 1993)]. Reading /user/jsrobin/fweb.sty... (No testval.aux file.) Reading testval.web... *1 *22 Writing testval.tex... *1 *22 Writing INDEX.tex...MODULES.tex... Done. CPU = 0.3 sec.; REAL = 0.5 sec. CPU/REAL = 63.0%. [FWEAVE: No errors were found.] //ValueAssignment/fweb 5822 > //ValueAssignment/fweb 5822 > latex testval.tex This is TeX, Version 3.1415 (C version 6.1) (testval.tex LaTeX2e <1994/06/01> (/usr/local/lib/texmf/tex/webs/fwebmacL.sty) (/usr/local/lib/texmf/tex/latex2e/base/latex209.def Entering LaTeX 2.09 compatibility mode. (/usr/local/lib/texmf/tex/latex2e/base/tracefnt.sty) (/usr/local/lib/texmf/tex/latex2e/base/latexsym.sty) (/usr/local/lib/texmf/tex/nfss2/nfot1.def)) (/usr/local/lib/texmf/tex/latex2e/base/article.cls Document Class: article 1994/06/02 v1.2s Standard LaTeX document class (/usr/local/lib/texmf/tex/latex2e/base/size12.clo)) No file testval.aux. *1 (/usr/local/lib/texmf/tex/latex2e/base/Ulasy.fd) ! Please use \mathaccent for accents in math mode. \.#1->{\accent 95 #1} l.49 \&{char} \1${}\ast\>{dbname}$ ${}=\.{"test"} ;$\2\6 ? h I'm changing \accent to \mathaccent here; wish me luck. (Accents are not the same in formulas as they are in text.) ? The neighborhood of the web file where things fail looks like: @ We open the database by use of the pgdb constructor. @= char *dbname = "test"; pgdb testdb(dbname); The .fweb file looks like: +PL +TD +wfwebmacL.sty +pLaTeX.options "" +pLaTeX.style "article" +psuffix.Cpp "C" When the same file is run through fweave and tex using a .fweb file like : +PT +TD +wfwebmac.sty +psuffix.Cpp "C" the files files are processed without error: fweave testval.web This is FWEAVE [UNIX version 1.40 (October 30, 1993)]. Reading /user/jsrobin/fweb.sty... Reading testval.web... *1 *22 Writing testval.tex... *1 *22 Writing INDEX.tex...MODULES.tex... Done. CPU = 0.3 sec.; REAL = 0.3 sec. CPU/REAL = 84.7%. [FWEAVE: No errors were found.] 5832 > tex testval.tex This is TeX, Version 3.1415 (C version 6.1) (testval.tex (/usr/local/lib/texmf/tex/webs/fwebmac.sty) *1 [1] [2] [3] [4] [5] [6] [7] [8] [9] *22 (INDEX.tex [10]) (MODULES.tex) [11] (CONTENTS.tex) [0] ) Output written on testval.dvi (12 pages, 26672 bytes). Transcript written on testval.log. Any help that can be offered on this would be deeply appreciated. -- ------------------------------------------------------------------------ Friends don't let friends do DOS. ================================================================================ Archive-Date: Wed, 19 Oct 1994 02:22:14 CDT Sender: owner-litprog@SHSU.edu From: clodius@lanl.gov (William B. Clodius) Reply-To: LitProg@SHSU.edu, clodius@LANL.GOV Subject: FrameMaker Literate Programming Date: Tue, 18 Oct 94 08:09:12 GMT Message-ID: To: LitProg@SHSU.EDU Hellow: I am interested in the potential for literate programming, but most literate programming tools appear to rely upon TeX or LaTeX. The team I am involved with are doing most of their documentation with FrameMaker. Does CLiP or some other tool facilitate literate programming with FrameMaker? ================================================================================ Archive-Date: Wed, 19 Oct 1994 02:22:25 CDT Sender: owner-litprog@SHSU.edu From: ssaund7000@aol.com (SSaund7000) Reply-To: LitProg@SHSU.edu, ssaund7000@AOL.COM Subject: New languages??? Date: 19 Oct 1994 01:15:03 -0400 Message-ID: <382a0n$j5m@newsbf01.news.aol.com> To: LitProg@SHSU.EDU I am seeking information about the latest and greatest in programming languages being used today. Could anyone using some the the newer languages please send me a short note, on which one, and how I might obtain it? Thank you. Shawn Saunders ssaund7000@aol.com ================================================================================ Archive-Date: Wed, 19 Oct 1994 02:23:28 CDT Sender: owner-litprog@SHSU.edu From: norman@flaubert.bellcore.com (Norman Ramsey) Reply-To: LitProg@SHSU.edu, norman@FLAUBERT.BELLCORE.COM Subject: Re: Style of header file inclusion Date: 18 Oct 1994 16:58:04 GMT Message-ID: <380uqs$l23@lowell.bellcore.com> To: LitProg@SHSU.EDU In article <37ullh$12pg@rs18.hrz.th-darmstadt.de>, felix gaertner wrote: >I'm currently going over some code I wrote a year ago and came across >an interesting point concerning literate programming style. I am >interested in how people write the inclusion of header files `literally'? >[distribute #include or write them all in one place?] Both C and Modula-3 have the property that it is poor practice, or actually incorrect, to #include the same file (IMPORT the same interface) twice. Since it is difficult to protect against this error when the #includes are distributed, I tend to write them all in one place. I usually put this near the end of the file. #include is even uglier than you might expect since there are order dependencies (e.g. sys/types.h before other files). ================================================================================ Archive-Date: Wed, 19 Oct 1994 02:25:13 CDT Sender: owner-litprog@SHSU.edu From: norman@flaubert.bellcore.com (Norman Ramsey) Reply-To: LitProg@SHSU.edu, norman@FLAUBERT.BELLCORE.COM Subject: Re: several docs from the same noweb file? Date: 18 Oct 1994 17:07:58 GMT Message-ID: <380vde$l47@lowell.bellcore.com> CC: Fernando Mato Mira To: LitProg@SHSU.EDU In article <37ut2d$9vn@disunms.epfl.ch>, Fernando Mato Mira wrote: > Would anybody care to give a short example of how >to write/use a noweb file to generate: > 1. A reference manual (only function signatures / public >slots of stuctures appear in the doc + some description + short example) > 2. A user's guide (no signatures, presentation follows a > different order, long examples). > 3. An implementors' manual (like a refence manual, but with > discussion about caveats, etc.). > 4. A classic literate program doc (need not include the examples). Don't even *think* about it. All the experiments I have tried along these lines have ended in disaster. The problem is, how are you going to edit and understand the source code for 4 different documents simultaneously? Especially such different documents? Slipping pieces of a reference manual into a document that is mostly a classic literate program seems OK. That is, it's not too hard to get the manual right, and the intercalated chunks aren't too disruptive. But even that is a bit creaky. >By the way, is it possible to `include' pure documentation >files into a noweb file? This question suggests that maybe you don't ``get'' the literate-programming paradigm. I suggest you read some of Don Knuth's papers, and also the Don Lindsay LP column from CACM, with special attention to reviewer Harold Thimbleby's comments. > a. Editing a file with correct code just do document seems a bad idea. > An error might be introduced accidentally. Leaving your documentation off in another file seems a bad idea. It might get *way* out of date. > b. A documentation might be cleaned-up by someone not authorized to change > the code. The literate document *is* the program. Someone not authorized to touch it ought not to touch it. > c. Touching the file with the code is uncool with make et al. Use cpif. > d. Too much doc mixed with the code makes it unpractical for programming > (unless non-code sections can be hidden in Emacs). If the documentation isn't helping you program it's not doing its job. ================================================================================ Archive-Date: Wed, 19 Oct 1994 08:34:36 CDT Sender: owner-litprog@SHSU.edu Message-ID: <199410191323.AA14439@noc.BelWue.DE> From: Aaron "Optimizer" Digulla Reply-To: LitProg@SHSU.edu, digulla@FH-KONSTANZ.DE Subject: Re: Style of header file inclusion To: LitProg@SHSU.edu, norman@FLAUBERT.BELLCORE.COM Date: Wed, 19 Oct 94 14:18:10 MEZ > In article <37ullh$12pg@rs18.hrz.th-darmstadt.de>, > felix gaertner wrote: > >I'm currently going over some code I wrote a year ago and came across > >an interesting point concerning literate programming style. I am > >interested in how people write the inclusion of header files `literally'? > >[distribute #include or write them all in one place?] > Both C and Modula-3 have the property that it is poor practice, or > actually incorrect, to #include the same file (IMPORT the same > interface) twice. Since it is difficult to protect against this error > when the #includes are distributed, I tend to write them all in one > place. I usually put this near the end of the file. #include is even > uglier than you might expect since there are order dependencies (e.g. > sys/types.h before other files). Well, modern compilers have a flag to avoid multiple inclusion of the same file. For my own projects, I use a method that does always work: 1. All files are protected with a #ifndef \uppercase{filename}, ie. if the file is in include/ as "project/main.h", the #ifndef would be #ifndef PROJECT_MAIN_H and then a #define so the contents of the file are read only once. 2. All #includes are also protected with #ifndef's (not really neccessary, but makes it a bit faster) 3. Last but not least every include-file can be read at any time (even alone). If it needs any other files, it can #include them because of 1 and 2. So the sub-file "project/sub.h" contains #ifndef PROJECT_MAIN_H # include #endif which solves all problems and makes life really easy (even more if you have an editor where you simply have to specify the name of the file and it creates the #ifndef..#include..#endif for you :) -- Aaron "Optimizer" Digulla. Author of XDME "(to) optimize: Make a program faster by improving the algorithms rather than by buying a faster machine." ================================================================================ Archive-Date: Wed, 19 Oct 1994 11:36:56 CDT Sender: owner-litprog@SHSU.edu From: "Denis B. Roegel" Reply-To: LitProg@SHSU.edu, Denis.Roegel@LORIA.FR Date: Wed, 19 Oct 1994 17:36:45 +0100 Message-ID: <199410191636.RAA04928@pandore.loria.fr> To: LitProg@SHSU.edu Subject: WEB for Turbo Pascal CC: roegel@lorraine.loria.fr Is there a WEB working with Turbo Pascal ? Denis. ================================================================================ Archive-Date: Wed, 19 Oct 1994 13:57:48 CDT Sender: owner-litprog@SHSU.edu From: iggjacob@sgi16 (Jacob Nielsen (c898594)) Reply-To: LitProg@SHSU.edu, iggjacob@SGI16 Subject: Re: Style of header file inclusion Date: 19 Oct 1994 13:34:39 GMT Message-ID: <38379f$oht@unidhp.uni-c.dk> To: LitProg@SHSU.EDU Norman Ramsey (norman@flaubert.bellcore.com) wrote: : In article <37ullh$12pg@rs18.hrz.th-darmstadt.de>, : felix gaertner wrote: : >I'm currently going over some code I wrote a year ago and came across : >an interesting point concerning literate programming style. I am : >interested in how people write the inclusion of header files `literally'? : >[distribute #include or write them all in one place?] : Both C and Modula-3 have the property that it is poor practice, or : actually incorrect, to #include the same file (IMPORT the same : interface) twice. Since it is difficult to protect against this error : when the #includes are distributed, I tend to write them all in one : place. I usually put this near the end of the file. #include is even : uglier than you might expect since there are order dependencies (e.g. : sys/types.h before other files). Normally I do like this: "code.cc"= #include "code.h" All my code files (.cc --- yes C++ code) has header files (.h), so I write that literately in the file and all the other #includes gets mentioned in . If there are many #includes I then do a: = This way I can find the #include's easily (IMHO) PS: to save myself from trouble, I always protect the .h files from being included more than once by using '#ifndef ... #define ... #endif' Regards, Jacob -- Jacob Nielsen iggjacob@bbar.dtu.dk ================================================================================ Archive-Date: Wed, 19 Oct 1994 13:58:28 CDT Sender: owner-litprog@SHSU.edu From: trashy@icicle.winternet.com (Barry Schwartz) Reply-To: LitProg@SHSU.edu, trashy@ICICLE.WINTERNET.COM Subject: Re: several docs from the same noweb file? Date: 19 Oct 1994 17:35:24 GMT Message-ID: <383lcs$bdm@blackice.winternet.com> To: LitProg@SHSU.EDU In article <37ut2d$9vn@disunms.epfl.ch> matomira@di.epfl.ch (Fernando Mato Mira) writes: ]Hello, ] ] Would anybody care to give a short example of how ]to write/use a noweb file to generate: ] 1. A reference manual (only function signatures / public ]slots of stuctures appear in the doc + some description + short example) ] 2. A user's guide (no signatures, presentation follows a ] different order, long examples). ] 3. An implementors' manual (like a refence manual, but with ] discussion about caveats, etc.). ] 4. A classic literate program doc (need not include the examples). I have argued (in this newsgroup, in fact) that there are literary reasons not to do this. My argument is that the manuals are works of literature on the same level as the literate program, and so should be written separately. There can be information about how to use the program written into the literate program itself, but good exposition style dictates that this information be terse. Notice that I make these arguments on grounds that come from expository writing and not traditional programming practice; I believe that literate programming is as much a task of expository writing as it is a task of producing a working program. Actually I view all serious programming this way (read "The Elements of Programming Style," by Kernighan and Plauger), but literate programming gives you better tools to do the job. An "implementor's manual" is an interesting thing to contemplate. The code itself should be documented in the literate program, and so there is no need for a separate manual. If you need one, then you haven't written an adequate literate program; go back and edit it. Designs present another obstacle, however. If the design is written in a precise language (say a variant of Ada, which I believe is used by IBM), then it should be possible to use noweb. Then you have at least two literate programs, one for the design and one for the code. Together, and along with the Requirements, they make up an implementor's manual, as well as the working program. ]By the way, is it possible to `include' pure documentation ]files into a noweb file? That's like asking if it is possible to love someone without commitment. The question shouldn't be "is it possible," but "is it valuable." "Is it valuable to love someone without commitment?" The answer is No. Similarly, there is little value in including the separate documentation within the noweb file. You might as well leave it separate. If you want to attach the documentation to the code in some secure way, you might as well put them together in a zip archive or something like that. You will gain none of the benefits of literate programming, of course. ] a. Editing a file with correct code just do document seems a bad idea. ] An error might be introduced accidentally. Code is not really correct unless you can edit it without great fear of breaking it. Most code has to be maintained, after all. Read "The Elements of Programming Style," by Kernighan and Plauger. ] b. A documentation might be cleaned-up by someone not authorized to change ] the code. This is a program configuration problem, not a problem with noweb. If this can happen then there is something wrong with the quality management process. ] c. Touching the file with the code is uncool with make et al. The cpif program addresses this problem. ] d. Too much doc mixed with the code makes it unpractical for programming ] (unless non-code sections can be hidden in Emacs). The last thing you want to do is ignore the explanation of what the code does, when you go in to modify the code. In a literate program, ideally the exposition and the code are an organic entity. This is not like what you might imagine, the code as "sufficient explanation of what's going on" and the documentation as "here's a few notes about what I've written." The way I view things, you should have the plain language notes there to keep you on course, and if you find something is wrong you should update the plain language along with the code. After all, the program is not correct unless both documentation and code are correct. (Read "The Elements of Programming Style," by Kernighan and Plauger.) Furthermore, if you really find that mixing docs and code is unpractical, then I think something is wrong, and I think I know what. The only way I can imagine this happening is if the program has bad modularity, in either the programming sense or the literate sense. There is some question as to how well Emacs modes handle literate programming, but that's an Emacs problem, not a literate-programming problem. ]PS: If what I want seems to point to some other system, please ] note that I program in Lisp. I agree with the view that a literate programming system should be language-independent. Noweb is such a system. Lisp is no problem for it. -- Barry Schwartz at MedGraphics trashy@winternet.com ================================================================================ Archive-Date: Thu, 20 Oct 1994 04:14:03 CDT Sender: owner-litprog@SHSU.edu Date: Thu, 20 Oct 94 09:59:44 +0100 From: kaufmann@analog.shraero.co.at (Roland Kaufmann SCHRACK AEROSPACE) Reply-To: LitProg@SHSU.edu, kaufmann@ANALOG.SHRAERO.CO.AT Message-ID: <9410200859.AA01812@analog.co.at.> To: LitProg@SHSU.edu, Denis.Roegel@loria.fr Subject: Re: WEB for Turbo Pascal Denis B. Roegel asked: > "Is there a WEB working with Turbo Pascal ?" In my view, Turbo Pascal is a particular implementation of (a compiler for) the programming language Pascal, for which the original (Donald E. Knuth's) WEB was developed. Without wanting to offend anyone, I consider using a non-portable, non-standard language like ``Turbo'' Pascal somewhat at odds with the concept of literate programming. I haven't used Turbo Pascal for a long time, but the old versions I used many years ago always annoyed me with their concept of fast compilation, quick fix of the first (syntax) error and continuing --- I do not think that reliable programs should be written like this, regardless whether they are literate or not. By the way, does anyone out there where I could get a copy of Brian Kernighan's article ``Why Pascal is not my favorite language''? Roland Kaufmann kaufmann@shraero.co.at ================================================================================ Archive-Date: Thu, 20 Oct 1994 12:28:46 CDT Sender: owner-litprog@SHSU.edu Date: Thu, 20 Oct 94 13:28:35 EDT From: Lee Wittenberg Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET To: Litprog@shsu.edu Subject: WinWordWEB and WinWord 6.0 Message-ID: Attention WinWordWEB users! (and David Thompson wrt the FAQ) Ed Baker has recently discovered (and pointed out to me) that the WinWordWEB macros do not work properly for Word 6.0 documents (strangely enough, Word 2.0 documents tangle fine under Word 6.0). The problem is due to the way the tangle macro extracts chunk names. Microsoft has ``improved'' Word, so that the (necessary) kludge that relied on inserted symbols having an Asc() code of 21 doesn't work any more. If anyone knows of (or can figure out) a fix to this problem, please let me know. In the meantime, please be warned (and David, please put a warning into the FAQ). -- Lee ------------------------------------------------------------------------ Lee Wittenberg | Halavah is a form of pie, and it has a Computer Science Department | specific gravity of 3.1416 and a specific Kean College of New Jersey | heat of .31416 Union, NJ 07083 | USA | -- D. E. Knuth | "The Potrzebie System of Weights leew@pilot.njin.net | and Measures" (1957) ------------------------------------------------------------------------ ================================================================================ Archive-Date: Thu, 20 Oct 1994 12:45:04 CDT Sender: owner-litprog@SHSU.edu Date: Thu, 20 Oct 94 13:44:52 EDT From: Lee Wittenberg Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET To: LitProg@shsu.edu, Denis.Roegel@loria.fr Subject: Re: WEB for Turbo Pascal Message-ID: Denis Roegel asks: > Is there a WEB working with Turbo Pascal ? The original WEB should work with Turbo Pascal (excluding extensions, but @f can help with that). Otherwise, the language-independent systems (noweb, nuweb, CLiP, etc.) will all work with Turbo. I've been doing some work in Turbo with noweb recently, which will eventually get posted to my samples.LP area. This stuff includes a filter that rearranges type definitions so that you can define them naturally: @ Explanations for [[SomeArrayType]] <>= SomeArrayType = ARRAY[1..whatever] OF Basetype; @ Explanations for [[Basetype]] <>= BaseType = ... without having to kludge things up so that [[Basetype]] will be defined before [[SomeArrayType]] as Pascal requires. The filter is a post-processor, so it should work with any LP system; it's a hack, so there are no guarantees (but it's an LP hack, so I won't be surprised if it does work for others). -- Lee ------------------------------------------------------------------------ Lee Wittenberg | Halavah is a form of pie, and it has a Computer Science Department | specific gravity of 3.1416 and a specific Kean College of New Jersey | heat of .31416 Union, NJ 07083 | USA | -- D. E. Knuth | "The Potrzebie System of Weights leew@pilot.njin.net | and Measures" (1957) ------------------------------------------------------------------------ ================================================================================ Archive-Date: Thu, 20 Oct 1994 14:53:44 CDT Sender: owner-litprog@SHSU.edu From: trashy@icicle.winternet.com (Barry Schwartz) Reply-To: LitProg@SHSU.edu, trashy@ICICLE.WINTERNET.COM Subject: Re: New languages??? Date: 20 Oct 1994 14:28:45 GMT Message-ID: <385uqt$qn6@blackice.winternet.com> To: LitProg@SHSU.EDU In article <382a0n$j5m@newsbf01.news.aol.com> ssaund7000@aol.com (SSaund7000) writes: ]I am seeking information about the latest and greatest in programming ]languages being used today. No matter what we do, Fortran will remain the latest and greatest. The only thing that changes is the meaning of "Fortran". :-) -- Barry Schwartz at MedGraphics trashy@winternet.com ================================================================================ Archive-Date: Fri, 21 Oct 1994 05:24:39 CDT Sender: owner-litprog@SHSU.edu From: sorges@messua.informatik.rwth-aachen.de (Dirk Sorges) Reply-To: LitProg@SHSU.edu, sorges@MESSUA.INFORMATIK.RWTH-AACHEN.DE Subject: C/C++ -> TeXinfo/HTML/LaTeX/nroff -man Date: 21 Oct 1994 10:05:26 GMT Message-ID: <3883p6$9dr@urmel.informatik.rwth-aachen.de> MIME-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit Keywords: C, C++, documentation, literate programming To: LitProg@SHSU.EDU Hi everybody! I'd like to have a tool for generating documentation from C/C++ source code. Features should be as follows: o source code and documentation go to one file o input is pure C/C++, ie., documentation stuff is held by comments, and no tangle-like source code extraction is needed o output is preferably TeXinfo or HTML, ie., a hypertext system; LaTeX and nroff -man could be supported as well o both user's and implementator's aspects of documentation are covered o very small interface: text between /// and newline (or /** and */, resp.) appears in the user's documentation, text between //// and newline (or /*** and */, resp.) additionaly appears in the implementator's documentation o cross-references are generated automatically: There's a node for each class, and a sub-nodes for each method; cross-references go to super- and sub-classes (which are known if a whole class library is scanned), and friends. Usage graph (calling/called by). Index. While there are lots of WEB-like tools, they have some major disadvantages: o Input is not pure C/C++ but a meta-language, and some sort of weave/tangle tools are needed. o Most tools are overfeatured, ie., due to their flexibility and language independence there is a large set of (IMHO) superflous commands. For example, if a tool knows about the language you don't need commands for cross referencing. It can be done automatically. o While there's a package (Graham Stoney's c2man) that nearly perfectly meets the minimal interface requirements (and the user's/implementator's differentiation should easily be added), it still has no C++ support, and lacks a true hypertext backend. Does anybody know whether there's a tool that provides some of the features mentioned above and that could be used as a base for enhancement? It should be quite difficult not to use a full-blown C++ parser. Would you suggest to use cppp? Or could it be useful (possible?) to add all that stuff to gcc? Any hints/suggestions/contributions are welcome. Thanx in advance Oliver PS: Here's a sample C++ file. Note that neither the code nor the documentation makes any sense, and many comments would not appear in a real program (those meta-documenting the documentation). PPS: The project's working title is DoX (DOcumentation eXtracter). ---------------------------------------------------------------------- // This is a two-slash comment. It will be ignored /* This is a one-asterisk comment. It will be ignored */ /* Three/four-slash comments are what DoX deals with, as well as two/three-asterisk comments. DoX will ignore comments with more slashes/asterisks (decoration): */ /// This will go to the user's guide (three slashes). /** This too (two asterisks). */ //// This goes to the implementators guide (four slashes). /*** This too (three asterisks) */ // This and the following line will be ignored: ////////////////////////////////////////////////////////////////////// /* This and the next line aren't used, either. */ /********************************************************************/ // Comments at the beginning of a file give a description of a group // of related classes (cluster). All classes defined in files in one // sub-directory could be also considered as cluster. Clusters could // be the base for structuring documents in a // chapter/section/... manner, whereas the class graph cannot since it // does not form a tree in the general case. /// The following classes provide a nice interface to the foobar /// package. // Comments in front of a class (no newline) give a genral overview. // Within a class declaration, there should be no further // documentation for methods, but the meaning of variables and // nested classes is mentioned. /// Class A deals with foo stuff. class A { public: A (int a); ~A (); protected: protA (int a); private: A (int a, int b); int privA (); // Note: since we are in the private class section, documentation // only goes to the implementator's guide, regardless wether we are using // 3 or 4 slashes. int _a; //// holds the number of a's int _b; /// holds the number of b's }; ////////////////////////////////////////////////////////////////////// // Within an implementation section, methods can be grouped using // comments surrounded by empty lines: /// Constructors/destructor /// Constructs A from one int. A::A (int a /** initial value */ ) { _a = a; } /// Construct A from two ints. //// The assignment to _a must come before the assignment to _b. A::A (int a, /// first value int b /** second value */) { _a = a; _b = b; } /// Destroy. A::~A () {} ////////////////////////////////////////////////////////////////////// /// Selectors /// Returns a. int A::privA () { return _a; } ////////////////////////////////////////////////////////////////////// /// Modifiers /// Assignment (int) A::protA (int a) { _a = a; } /// B adds bar features to A and thus makes it a real foobar. class B : public A { public: B (int b); ~B (); private: int _b; }; /// Constructors/destructor /// Contruct from int. //// FIXME: magic number should be replaced. B::B (int b /** initial value without offset */) : A (b + 6060842), _b (b) {} /// Destroy. B::~B () {} ////////////////////////////////////////////////////////////////////// /// Supporting functions. /// The qsort subroutine sorts a table of data in place. It uses the /// quicker-sort algorithm. //// The quicker-sort algorithm is as follows: ... //// See also Hoare: "..."; Knuth: "The art of computer programming" void qsort ( void* base, /// pointer to first element int nElems, /// number of elements int elemSize, /// size of each element /** pointer to comparison function */ int /// <0: lhs < rhs /// ==0: lhs == rhs /// >0: lhs > rhs (*compare) (const void* lhs, /** left hand side of comparison */ const void* rhs /** right hand side of comparison */) ) {} ---------------------------------------------------------------------------- Oliver Imbusch snail mail: PowerStone Parallelrechner GmbH e-mail: flabes@parsytec.de Kaiserstr. 100 phone: +49 (24 07) 953-42 D-52134 Herzogenrath fax: +49 (24 07) 953-50 Germany ---------------------------------------------------------------------------- ================================================================================ Archive-Date: Fri, 21 Oct 1994 06:10:25 CDT Sender: owner-litprog@SHSU.edu From: utcke@tu-harburg.d400.de (Sven Utcke) Reply-To: LitProg@SHSU.edu, utcke@TU-HARBURG.D400.DE Subject: cpif, was: several docs from the same noweb file? Date: 21 Oct 1994 09:43:14 GMT Message-ID: <3882fi$pmr@rztsun.tu-harburg.de> To: LitProg@SHSU.EDU In article <383lcs$bdm@blackice.winternet.com>, trashy@icicle.winternet.com (Barry Schwartz) writes: |> In article <37ut2d$9vn@disunms.epfl.ch> |> matomira@di.epfl.ch (Fernando Mato Mira) writes: |> |> ] c. Touching the file with the code is uncool with make et al. |> |> The cpif program addresses this problem. This is now the second time that I hear about cpif. What is it? Can it be used with, say, FWEB (the literate program of my choice)? If so, where can I get it (ask archie, I suppose?)? Thanks Sven ================================================================================ Archive-Date: Fri, 21 Oct 1994 07:20:02 CDT Sender: owner-litprog@SHSU.edu From: schrod@iti.informatik.th-darmstadt.de (Joachim Schrod) Reply-To: LitProg@SHSU.edu, schrod@ITI.INFORMATIK.TH-DARMSTADT.DE Subject: Re: cpif, was: several docs from the same noweb file? Date: 21 Oct 1994 11:20:32 GMT Message-ID: <388860$nl4@rs18.hrz.th-darmstadt.de> To: LitProg@SHSU.EDU In article <3882fi$pmr@rztsun.tu-harburg.de>, utcke@tu-harburg.d400.de (Sven Utcke) writes: > In article <383lcs$bdm@blackice.winternet.com>, trashy@icicle.winternet.com (Barry Schwartz) writes: > |> In article <37ut2d$9vn@disunms.epfl.ch> > |> matomira@di.epfl.ch (Fernando Mato Mira) writes: > |> > |> ] c. Touching the file with the code is uncool with make et al. > |> > |> The cpif program addresses this problem. > > This is now the second time that I hear about cpif. What is it? cpif is part of the noweb distribution, it copies standard input to a file only if the contents did not change. (Or did change, as you want.) ---------------- snip snap ---------------------------------------- #!/bin/sh # cpif [ -eq -ne ] file... # copy standard input to each of the named files # if new * old is true or old doesn't exist; # * defaults to -ne PATH=/bin:/usr/bin # set -x op=-ne case "$1" in -eq|-ne) op=$1; shift ;; -*) echo 'Usage: '`basename $0`' [ -eq -ne ] file...' 1>&2; exit 2 esac case $# in 0) echo 'Usage: '`basename $0`' [ -eq -ne ] file...' 1>&2; exit 2 esac new=/tmp/$$ trap 'rm -f $new; exit 1' 1 2 15 # clean up files cat >$new for i do cmp -s $new $i case $op$? in -eq0|-ne1|*2) cp $new $i esac done rm -f $new ---------------- snip snap ---------------------------------------- Actually, not long ago I needed to extend this to `real' file copy operations, so here is my copyif. (E.g., I use it for parser generators like PCCTS who create the scanner as an intermediate file and would trigger spurious compilation of the scanner as it has changed.) As it's roughly upward compatible (as long as only one file is `cpif'ed), I use it for noweb, too... :-) ---------------- snip snap ---------------------------------------- #!/bin/sh # $ITI: copyif,v 1.1 1994/07/14 12:55:24 schrod Exp $ #---------------------------------------------------------------------- # # copyif -- copy files if comparison succeeds # # (history at end) # SYNOPSIS # # copyif [-eq | -ne] file # copyif [-eq | -ne] file1 file2 # copyif [-eq | -ne] file ... dir # # # copyif copies a file if a comparison succeeds or if the target file # does not exist. The comparison is either a test if the contents is # equal (-eq) or if it has changed (-ne). The default is -ne. # # The first call form copies standard input to file. The second # one copies file1 to file2. The third copies all # filess into directory dir. # # The source file(s) and also the target file/dir must be readable, # and target must be writable. # # A typical usage is in Makefiles where a file shall only be copied if # it has changed. # # cmd=`basename $0` usage() { cat <<_EOF_ >&2 usage: $cmd: [-eq | -ne] file $cmd: [-eq | -ne] file1 file2 $cmd: [-eq | -ne] file ... dir _EOF_ exit $1 } # parse options... test $# = 0 -o "$1" = '-?' && usage 1 # default is -ne case "$1" in -ne|-eq) test=$1 shift ;; *) test='-ne' ;; esac # one parameter => save source from stdin in $tmp_file if [ $# = 1 ] then tmp_file=/tmp/copyif$$ trap "rm -f $tmp_file" 0 1 2 3 15 cat >$tmp_file src=$tmp_file dest_file=$1 dest_dir='' fi # two parameter if [ $# = 2 ] then src=$1 # Target argument might be a directory, ie, this might be a # call of form 3. if [ -d "$2" ] then dest_file='' dest_dir=$2 else dest_file=$2 dest_dir='' fi fi # n parameter # $1 .. $n-1 are $src # $n is $dest_dir if [ $# -gt 2 ] then # Split list of arguments on last blank and assign thereby the # source files to $src. src=`expr "$*" : '\(.*\) '` dest_file='' # Discard all source arguments shift `expr $# - 1` # Check if target argument is a directory, complain if not if [ ! -d "$1" ] then echo "$cmd: $1: not a directory." >&2 usage 2 else dest_dir=$1 fi fi # pre: # $src is list of source files # either $dest_dir is destination directory # or $dest_dir is empty and $dest_file is destination file and # $src is only one file result_code=0 for file in $src do test "$dest_dir" && dest_file=$dest_dir/$file # now $dest_file holds the target file name # check if it exists if [ -f $dest_file ] then cmp $file $dest_file >/dev/null result="$test$?" case "$result" in *2) # error in cmp command, message was issued exit 2 ;; -eq1|-ne0) continue ;; esac fi cp $file $dest_file result_code=`expr $result_code + $?` done # If there was at least one error in cp, add 10 to the result code. # This way we get a unique exit code that we can distinguish from # internal errors. test $result_code != 0 && result_code=`expr $result_code + 10` exit $result_code #====================================================================== # # $ITIlog: copyif,v $ # Revision 1.1 1994/07/14 12:55:24 schrod # Initial revision. # ---------------- snip snap ---------------------------------------- Enjoy, Joachim -- =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= Joachim Schrod Email: schrod@iti.informatik.th-darmstadt.de Computer Science Department Technical University of Darmstadt, Germany ================================================================================ Archive-Date: Sat, 22 Oct 1994 07:23:41 CDT Sender: owner-litprog@SHSU.edu From: kasper@iesd.auc.dk (Kasper Osterbye) Reply-To: LitProg@SHSU.edu, kasper@IESD.AUC.DK Subject: Re: several docs from the same noweb file? Date: 20 Oct 1994 10:16:06 GMT Message-ID: MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit To: LitProg@SHSU.EDU >>>>> "Norman" == Norman Ramsey writes: Norman> In article <37ut2d$9vn@disunms.epfl.ch>, Fernando Mato Norman> Mira wrote: >> Would anybody care to give a short example of how to write/use >> a noweb file to generate: 1. A reference manual (only function >> signatures / public slots of stuctures appear in the doc + some >> description + short example) 2. A user's guide (no signatures, >> presentation follows a different order, long examples). 3. An >> implementors' manual (like a refence manual, but with >> discussion about caveats, etc.). 4. A classic literate program >> doc (need not include the examples). Norman> Don't even *think* about it. All the experiments I have Norman> tried along these lines have ended in disaster. The Norman> problem is, how are you going to edit and understand the Norman> source code for 4 different documents simultaneously? Norman> Especially such different documents? Norman> Slipping pieces of a reference manual into a document that Norman> is mostly a classic literate program seems OK. That is, Norman> it's not too hard to get the manual right, and the Norman> intercalated chunks aren't too disruptive. But even that Norman> is a bit creaky. Well, but the problem remains then. Literate programming is well suited to make sure that the program and its low level exposition are kept up to date, but how can we ensure that the other documents Fernando mentions has the same quality? You say that you have attempted it in many different ways - are there no hope to extend the literate paradigm to include the apparently natual thing Fernando wants to do? -- Kasper -- Kasper Osterbye Internet: kasper@iesd.auc.dk Aalborg University FAX: +45 98 15 81 29 Fredrik Bajers vej 7E, 9220 Aalborg Phone: (W) +45 98 15 85 22 DENMARK. (H) +45 98 11 09 25 ================================================================================ Archive-Date: Mon, 24 Oct 1994 05:10:14 CDT Sender: owner-litprog@SHSU.edu Date: Mon, 24 Oct 1994 11:06:48 +0000 (GMT) From: "Eric W. van Ammers, LUW, tel: (+31)8370-83356" Reply-To: LitProg@SHSU.edu, AMMERS@RCL.WAU.NL Subject: Re: several docs from the same noweb file? To: LitProg@SHSU.edu Message-ID: <01HINHSBXJ1UFOGKL0@RCL.WAU.NL> MIME-Version: 1.0 Content-Transfer-Encoding: 7BIT IN%"kasper@IESD.AUC.DK" 22-OCT-1994 13:43:47.93 writes: =Well, but the problem remains then. Literate programming is well =suited to make sure that the program and its low level exposition are =kept up to date, but how can we ensure that the other documents =Fernando mentions has the same quality? You say that you have =attempted it in many different ways - are there no hope to extend the =literate paradigm to include the apparently natual thing Fernando =wants to do? A relavant paper about this problem appeared recently: Jim Welsh, Jun Han Software Documents: concepts and tools Software-Concepts and Tools (1994) 15: 12-25 Eric W. van Ammers ================================================================================ Archive-Date: Mon, 24 Oct 1994 08:54:27 CDT Sender: owner-litprog@SHSU.edu Date: Mon, 24 Oct 1994 09:54:22 +0059 (EDT) From: ed j baker Reply-To: LitProg@SHSU.edu, ejb@WORLD.STD.COM Subject: Re: several docs from the same noweb file? To: LitProg@SHSU.edu, AMMERS@RCL.WAU.NL CC: LitProg@SHSU.edu Message-ID: MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII On Mon, 24 Oct 1994, Eric W. van Ammers, LUW, tel: (+31)8370-83356 wrote: > A relavant paper about this problem appeared recently: > Jim Welsh, Jun Han > Software Documents: concepts and tools > Software-Concepts and Tools (1994) 15: 12-25 > > Eric W. van Ammers > Is this paper available on the World Wide Web? ================================================================================ Archive-Date: Mon, 24 Oct 1994 11:18:41 CDT Sender: owner-litprog@SHSU.edu Date: Mon, 24 Oct 94 12:18:22 EDT From: Lee Wittenberg Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET To: LitProg@shsu.edu, sorges@messua.informatik.rwth-aachen.de Subject: Re: C/C++ -> TeXinfo/HTML/LaTeX/nroff -man Message-ID: Oliver Imbusch writes: > I'd like to have a tool for generating documentation from C/C++ source > code. Features should be as follows: > > o source code and documentation go to one file > > o input is pure C/C++, ie., documentation stuff is held by > comments, and no tangle-like source code extraction is > needed > > o very small interface: text between /// and newline (or /** > and */, resp.) appears in the user's documentation, text > between //// and newline (or /*** and */, resp.) additionaly > appears in the implementator's documentation > > While there are lots of WEB-like tools, they have some major > disadvantages: > > o Input is not pure C/C++ but a meta-language, and some sort > of weave/tangle tools are needed. I feel it's necessary to point out that your ///, /**, etc. conventions are also a ``meta-language,'' but then again, ``a foolish consistency is the hobgoblin of little minds.'' ;-) -- Lee ------------------------------------------------------------------------ Lee Wittenberg | Halavah is a form of pie, and it has a Computer Science Department | specific gravity of 3.1416 and a specific Kean College of New Jersey | heat of .31416 Union, NJ 07083 | USA | -- D. E. Knuth | "The Potrzebie System of Weights leew@pilot.njin.net | and Measures" (1957) ------------------------------------------------------------------------ ================================================================================ Archive-Date: Mon, 24 Oct 1994 11:24:30 CDT Sender: owner-litprog@SHSU.edu Date: Mon, 24 Oct 94 12:24:24 EDT From: Lee Wittenberg Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET To: LitProg@shsu.edu, utcke@tu-harburg.d400.de Subject: Re: cpif, was: several docs from the same noweb file? Message-ID: Sven Utcke writes: > In article <383lcs$bdm@blackice.winternet.com>, trashy@icicle.winternet.com (Barry Schwartz) writes: > |> In article <37ut2d$9vn@disunms.epfl.ch> > |> matomira@di.epfl.ch (Fernando Mato Mira) writes: > |> > |> ] c. Touching the file with the code is uncool with make et al. > |> > |> The cpif program addresses this problem. > > This is now the second time that I hear about cpif. What is it? Can > it be used with, say, FWEB (the literate program of my choice)? If > so, where can I get it (ask archie, I suppose?)? cpif is a tool that comes with the noweb distribution. It's designed to work with makefiles, and should work with any system. You can find it in the noweb distribution in the CTAN archives (under the shell directory; the man page cpif.1 is in the xdoc directory). Cpif is a shell script, but Barry Schwartz has ported it to DOS, but this version hasn't been officially released yet, because Lee Wittenberg has been to d--- lazy to build a new DOS noweb distribution with it enclosed. -- Lee ------------------------------------------------------------------------ Lee Wittenberg | Halavah is a form of pie, and it has a Computer Science Department | specific gravity of 3.1416 and a specific Kean College of New Jersey | heat of .31416 Union, NJ 07083 | USA | -- D. E. Knuth | "The Potrzebie System of Weights leew@pilot.njin.net | and Measures" (1957) ------------------------------------------------------------------------ ================================================================================ Archive-Date: Tue, 25 Oct 1994 03:06:45 CDT Sender: owner-litprog@SHSU.edu Date: Tue, 25 Oct 1994 09:06:29 +0000 (GMT) From: "Eric W. van Ammers, LUW, tel: (+31)8370-83356" Reply-To: LitProg@SHSU.edu, AMMERS@RCL.WAU.NL Subject: Re: FrameMaker Literate Programming To: LitProg@SHSU.edu Message-ID: <01HIORYICBEQFOFYCK@RCL.WAU.NL> MIME-Version: 1.0 Content-Transfer-Encoding: 7BIT Regarding your mail of 19-oct-1994 on the question if CLiP can be used with Frame Maker, I expect no problem. CLiP can be used in combination with any system which provides for a decent ASCII-export. Regards Eric W. van Ammers ======================================================================= Eric W. van Ammers Department of Computer Science Wageningen Agricultural University Dreijenplein 2 E-mail: ammers@rcl.wau.nl 6703 HB Wageningen voice: +31 (0)8370 83356/84154 The Netherlands fax: +31 (0)8370 84731 ================================================================================ Archive-Date: Tue, 25 Oct 1994 16:12:20 CDT Sender: owner-litprog@SHSU.edu From: "Denis B. Roegel" Reply-To: LitProg@SHSU.edu, Denis.Roegel@LORIA.FR Date: Tue, 25 Oct 1994 22:12:14 +0100 Message-ID: <199410252112.WAA17060@pandore.loria.fr> To: LitProg@SHSU.edu Subject: WEB question CC: roegel@lorraine.loria.fr Hello, How can I break after a `begin' in WEB ? I tried @/ but this works almost everywhere but after a `begin'. Thanks, Denis. ================================================================================ Archive-Date: Wed, 26 Oct 1994 05:36:19 CDT Sender: owner-litprog@SHSU.edu From: pensa@c700-2.sm.dsi.unimi.it (Giovanni MenoZero Pensa) Reply-To: LitProg@SHSU.edu, pensa@C700-2.SM.DSI.UNIMI.IT Subject: aut OOP aut LitProg? Date: 26 Oct 1994 11:25:40 +0100 Message-ID: <38lar4$6ap@c700-2.sm.dsi.unimi.it> To: LitProg@SHSU.EDU Well, I have a question... I program in C++ and I use CWEB. No REAL problems. But... I'm not sure if LitProg is very useful with OOP. I think (or just feel) that some features were useful year ago, with a standard Pascal or a bare C. (Ops... will the great DEK kill me for a sentence like this?) LitProg can help with global data? A C++ prog *shouldn't* have global data. With LitProg you can declare your vars were you want? Also with C++. (the problem is that with CWEB's philosophy, the wars are moved at the beginning, sigh) (etc.) You know, I'm not versus WEB. Really. I'm just saying that some things are useless (and sometimes are a real problem) and that maybe I need others features. (I don't know what. Yet.) Ex: @* Point. This is a useless Point class. @= class Point { int x, y; public:@/ Point(); Point( Point& ); Point( int, int ); }; @<|Point|'s functions@>@; @ This is the first constructor. @<|Point|'s functions@>= inline Point::Point() { x = y = 0; } @ This is the second constructor. @<|Point|'s functions@>= inline Point::Point( Point& p ) { x = p.x; y = p.y; } That's (more or less) how I work. The things I don't like: - I'd like "Point& p" more than "Point &p". - I'd like that after "public:" CWEB put a NewLine. - ... (Yes, sometimes I create bigger functions...) And, in general, in this way LitProg is not really useful. The functions are small "di per se", they are "inline", they are logically under the class, they tell a lot just by their name, ... Ok, I know I'm confused and confusing. I just want to know your opinion. "How do you write (small) classes with C++ and CWEB?" "Is your style better than mine?" "Do you think there are some problems, too?" P.S. I still don't believe that I'm writing >against< DEK! Donald, will you ever forgive me? (I know you don't read email...) g. -- Giovanni MenoZero Pensa http://www.dsi.unimi.it/Users/Students/pensa/home.html ================================================================================ Archive-Date: Wed, 26 Oct 1994 07:38:55 CDT Sender: owner-litprog@SHSU.edu From: maavl@cwi.nl (Marc van Leeuwen) Reply-To: LitProg@SHSU.edu, maavl@CWI.NL Subject: Re: aut OOP aut LitProg? Message-ID: Date: Wed, 26 Oct 1994 12:27:28 GMT To: LitProg@SHSU.EDU In article <38lar4$6ap@c700-2.sm.dsi.unimi.it>, pensa@c700-2.sm.dsi.unimi.it (Giovanni MenoZero Pensa) writes: |> I'm not sure if LitProg is very useful with OOP. |> I think (or just feel) that some features were useful year ago, |> with a standard Pascal or a bare C. So why worry? You don't _have_ to use any features just for their sake. |> LitProg can help with global data? |> A C++ prog *shouldn't* have global data. |> |> With LitProg you can declare your vars were you want? |> Also with C++. |> (the problem is that with CWEB's philosophy, the wars are moved |> at the beginning, sigh) Although you _can_ declare variables anywhere you want, it is preferable to declare them as local as possible wherever you can. In C this is usually possible, in Pascal only if you are writing very small functions. So WEB can help you out in difficult cases, but please don't misuse this feature to write unnecessarily bad programs. |> The things I don't like: |> - I'd like "Point& p" more than "Point &p". |> - I'd like that after "public:" CWEB put a NewLine. So (unless you want to keep typing explicit format controls all the time) you want to modify the grammar of CWEAVE. A problem, and in my opinion the most serious problem, with (Levy/Knuth) CWEB is that its grammar is so hard to understand, and therefore to modify. Another problem is specific to C/C++, namely that it's syntax for declarations is so horrible. I like to write declarations like |char* s="string";| myself, but the sad fact is that in C a declaration is a type specifier followed by an _expression_, and the |*| belongs to the expression syntactically, not to the type specifier; this makes it almost impossible to specify rules that separate the |*| from the |s| in my example and are still capable of handling the general case properly. Now I believe the use of |&| in C++ declarations is more limited than that of |*|, so if you make |&| into a special syntactic category, you might have a better chance of getting your first wish satisfied. Your second wish should be easy: rule 90 reads |public_like colon -> tag|, and if you include a forced break at the end of the translation for this rule, you should get what you want. |> And, in general, in this way LitProg is not really useful. The functions |> are small "di per se", they are "inline", they are logically under the |> class, they tell a lot just by their name, ... If your program consists mainly of such functions, then chances are it is not doing much algorithms, just a lot of administration (in my opinion this is the area where object oriented programming is most applicable). I have written such a program myself (a small window application) and found that the benefits of literate programming are not very great here, mainly because there is so little to say about the code that is not immediately obvious. Nevertheless there is no reason not to use CWEB in such cases; it still makes your code and the few comments you do have look a lot nicer. In any case there is no obligation to break up a small function into multiple modules just because you are trying to practice Literate Programming. |> Donald, will you ever forgive me? (I know you don't read email...) You can be pretty certain that Don Knuth doesn't read this news group. Nor do I think he objects to people using Literate Programming in a different way than he does himself. Marc van Leeuwen CWI, Amsterdam ================================================================================ Archive-Date: Wed, 26 Oct 1994 08:31:42 CDT Sender: owner-litprog@SHSU.edu From: tsl1@cornell.edu (Timothy Larkin) Reply-To: LitProg@SHSU.edu, tsl1@CORNELL.EDU Subject: Re: aut OOP aut LitProg? Date: 26 Oct 1994 12:57:42 GMT Message-ID: To: LitProg@SHSU.EDU In article <38lar4$6ap@c700-2.sm.dsi.unimi.it>, pensa@c700-2.sm.dsi.unimi.it (Giovanni MenoZero Pensa) wrote: > I'm not sure if LitProg is very useful with OOP. I am currently working on an application in C++ using LP. I find it very useful. I have a standard approach that works like this: @* The name of a class. @(foo.h@>= #include "baseclass.h" class Foo : public baseclass { private: @@; public: @@; protected: @@; }; @ @c #include "foo.h" @@; @ @ Destructors and constructors. @= Foo(); ~Foo(); @ @= Foo::Foo() { @@; } Foo::~Foo() { @@; } @ Now I proceed on an exposition that often centers on member variables. For instance, I use an array |frob| like this. LP allows me to collect the diverse declartions into a single place. @= char *frob; @ @= frob = new char[80]; @ @= delete [] frob; @ Define some access functions. @= const char *GetFrob(); void SetFrob(char*); @ @= const char *Foo::GetFrob() { return frob; } void Foo::SetFrob(char *) { ...etc. Enough of that. You get the idea. I find that LP pays off handsomely in OOP. If I need to make a change to |frob|'s contract, I know that I will find it spelled out in one section of text. I don't have to jump around between include files and main body, constructors, destructors, access functions, etc. Furthermore, when I develop classes that are closely linked with each other, I can easily write the code in a single WEB, interdigitating code from different classes. @ @= void Foo::DoSomething() {...} @ This implies that |Bar| must do something else. @= void Bar::DoSomethingElse() {...} @ Now |Foo| can go ahead with the final act. void Foo::FinalAct() {...} I think that LP and OOP are made for each other, even more perhaps than LP and C. C++ is such a clumsy tool: it needs all the help it can get! Cordially, -- tsl1@cornell.edu Timothy Larkin He said that the world was sentient to its core and secret and black beyond men's imagining and that its nature did not reside in what could be seen or not seen. --Cormac McCarthy, "The Crossing" Public key 768/6CC32A85 ================================================================================ Archive-Date: Wed, 26 Oct 1994 10:43:49 CDT Sender: owner-litprog@SHSU.edu From: jsrobin@afterlife.ncsc.mil (John S. Robinson) Reply-To: LitProg@SHSU.edu, jsrobin@AFTERLIFE.NCSC.MIL Subject: CWEB - ...scrap/token/text capacity exceeded. Message-ID: <1994Oct25.180435.21228@afterlife.ncsc.mil> Keywords: CWEB Date: Tue, 25 Oct 1994 18:04:35 GMT To: LitProg@SHSU.EDU While using CWEB I got the error message: ! Sorry, scrap/token/text capacity exceeded. . . . (That was a fatal error, my friend.) The obvious question is "What do I do now?", and what does the error mean? -- ------------------------------------------------------------------------ Friends don't let friends do DOS. ================================================================================ Archive-Date: Wed, 26 Oct 1994 13:13:34 CDT Sender: owner-litprog@SHSU.edu From: Multimedia@cce.ubc.ca (Charles Tremewen) Reply-To: LitProg@SHSU.edu, Multimedia@CCE.UBC.CA Subject: MultiCom'94 Conference Update Date: Tue, 25 Oct 1994 11:04:19 -0800 Message-ID: To: LitProg@SHSU.EDU Dear Colleague, This is a friendly reminder that MultiComm'94 registration has been extended to October 28 for the regular registration fee of $295. This includes: Keynote dinner with Nicholas Negroponte, proceedings, all meals throughout the two days, unlimited access to the vendor exhibits and attendace to all concurrent sessions. After October 28, registration will increase to $325. Join us for this spectacular event and have a great time with Vancouver's multimedia community and the numerous international delegates attending. Pre-registration is November 1st 6:30pm and will feature "Young Producers" from grades 7-12 and their productions. Conference Dates: November 2/3, 1994 Location: The Westin Bayshore, Vancouver, B.C. Canada Register by phone (Visa /Mastercard) - (604)222-5251 or (604)222-5256 Need more information? Call (604)822-0691 Sincerely, Charles Tremewen Conference Chair, MultiComm'94 ___________________________________________________________________ ..."The medium is the message" because it is the medium that shapes and controls the scale and form of human association and action. Marshall McLuhan, Understanding Media, 1964 ___________________________________________________________________ Charles Tremewen, Coordinator-Computer Science, Multimedia Studies Certificate & Internet Certificate Programs, Chair-MultiComm'94, Co-Chair WRITE'95 - UBC Continuing Studies, 5997 Iona Drive, Vancouver, B.C. V6T 1Z1,Canada Phone(604)822-0692 Fax:(604) 822-0694/822-9826 ================================================================================ Archive-Date: Wed, 26 Oct 1994 13:47:52 CDT Sender: owner-litprog@SHSU.edu Date: Wed, 26 Oct 1994 11:47:34 -0700 From: farzin@protocol.com (Farzin Guilak) Reply-To: LitProg@SHSU.edu, farzin@PROTOCOL.COM Message-ID: <9410261847.AA06977@fletsom.Protocol.COM> To: litprog@shsu.edu Subject: Format definitions for Motif/Xt Does anyone have a '.w' file consisting of the format definitions for Motif and Xt? I'm looking for something similar to xview_types.w and xlib_types.w included in the cweb distribution. Thanks, Farzin ____________________ Farzin G. Guilak farzin@protocol.com +1 503 526 4389 ================================================================================ Archive-Date: Wed, 26 Oct 1994 19:56:22 CDT Sender: owner-litprog@SHSU.edu From: A7621GAC@AWIUNI11.EDVZ.UniVie.AC.AT Reply-To: LitProg@SHSU.edu, A7621GAC@AWIUNI11.EDVZ.UNIVIE.AC.AT Subject: Re: CWEB - ...scrap/token/text capacity exceeded. Date: Thu, 27 Oct 94 01:34:10 MEZ Message-ID: <1705C1622.A7621GAC@AWIUNI11.EDVZ.UniVie.AC.AT> Keywords: CWEB To: LitProg@SHSU.EDU In article <1994Oct25.180435.21228@afterlife.ncsc.mil> jsrobin@afterlife.ncsc.mil (John S. Robinson) writes: > >While using CWEB I got the error message: > >! Sorry, scrap/token/text capacity exceeded. >. >. >. >(That was a fatal error, my friend.) > > > >The obvious question is "What do I do now?", and what does the error > mean? If you wrote your program in small pieces, this should not happen. Perhaps you forgot to change back your writing mode? (I.e. forgetting @ or @c) If this is not the case, you must recompile CWEAVE and increase the appropriate array (I don't remember its name). Werner ================================================================================ Archive-Date: Thu, 27 Oct 1994 04:50:18 CDT Sender: owner-litprog@SHSU.edu From: marty@cs.hope.edu (Ben Marty) Subject: Re: New languages??? Date: 24 Oct 1994 15:36:06 GMT Message-ID: <38gk97$k3k@hydra.cs.hope.edu> Reply-To: LitProg@SHSU.edu, marty@cs.hope.edu To: LitProg@SHSU.EDU It would help to know what kind of computer you plan to use before selecting a language. --- Ben Marty (marty@cs.hope.edu) Computer Science Major at: Hope College in Holland, MI ( fortune)/( time) = happiness happiness * time = fortune ================================================================================ Archive-Date: Thu, 27 Oct 1994 19:00:39 CDT Sender: owner-litprog@SHSU.edu From: marcus@x4u2.desy.de (Marcus Speh) Reply-To: LitProg@SHSU.edu, marcus@X4U2.DESY.DE Subject: Re: aut OOP aut LitProg? Date: 26 Oct 1994 11:31:34 GMT Message-ID: To: LitProg@SHSU.EDU Did you have a look at http://info.desy.de/user/projects/LitProg.html on that page, you will find a link to useful discussion contribs on OOP and LitProg. ms -- | Marcus Speh | tel (033762) 77 0 / (030) 3959808 | | DESY-IfH Zeuthen | fax (033762) 77 216 | | Platanenallee 6 | Internet: marcus@ifh.de | | 15738 Zeuthen (Berlin),Germany | WWW http://www.desy.de/www/marcus.html | ================================================================================ Archive-Date: Fri, 28 Oct 1994 05:31:22 CDT Sender: owner-litprog@SHSU.edu From: norman@flaubert.bellcore.com (Norman Ramsey) Reply-To: LitProg@SHSU.edu, norman@FLAUBERT.BELLCORE.COM Subject: Re: several docs from the same noweb file? Date: 28 Oct 1994 05:05:41 GMT Message-ID: <38q0r5$7jj@lowell.bellcore.com> To: LitProg@SHSU.EDU In article , Kasper Osterbye wrote: >Well, but the problem remains then. Literate programming is well >suited to make sure that the program and its low level exposition are >kept up to date, but how can we ensure that the other documents >Fernando mentions has the same quality? You say that you have >attempted it in many different ways - are there no hope to extend the >literate paradigm to include the apparently natual thing Fernando >wants to do? I think extending the literate paradigm is a misguided idea. Literate programming is about writing documents that are also programs. The mechanisms commonly used to create literate programs also appear to be capable of combining multiple documents into a single source, but that's an accident, and we shouldn't let it seduce us into insisting on doing things that way. In fact, literate programming as practiced today is really good only for producing single documents. I know of two experiments that are not failures. One is one of mine, which includes portions of a reference manual (as *code*) in a document that is the implementation of the tool described in the reference manual. This scheme is workable only because the size of the reference-manual fragments is a tiny fraction of the whole document, well under 10%. (The bulk of the manual lives in its own source files anyway.) I would not call it a success, but it's not a failiure, either. I'm not sure the benefit we get outweighs the added difficulty of editing the source. I may be able to tell better as we see how the implementation and reference manual evolve over time. I certainly wouldn't advocate that other people do this except as an experiment. The one experiment I know of that was successful was that of Jon Bentley and others at Bell Labs in describing the PRL5 language. In that case: - six or so documents were generated from the same source. - there was no code involved, only documentation. - the six documents had identical outlines (structures) - (I believe) documents didn't share text For this limited problem, they got good results using a custom little language to generate the documents. I see no way of generalizing to documents that have different structures. I've seen claims for hypertext systems, but I'm not sure hypertext is a 'document' in the sense I'm used to thinking of. I have found hypertext useful for browsing to find bits of information, but much less so for reading in bulk to get a coherent, in-depth understanding of anything. I'm also not sure what it means to have *multiple* documents if everything's connected together in a hypertext web. As for where we go from here, I think people ought to be thinking about new tools and techniques to support the creation of multiple documents with different contents and structure but which have to be kept consistent. It's a hard problem, and I'm not sure the skills of the literate programmer are a great match for it. Norman ================================================================================ Archive-Date: Fri, 28 Oct 1994 07:47:54 CDT Sender: owner-litprog@SHSU.edu From: norman@flaubert.bellcore.com (Norman Ramsey) Reply-To: LitProg@SHSU.edu, norman@FLAUBERT.BELLCORE.COM Subject: Re: C/C++ -> TeXinfo/HTML/LaTeX/nroff -man Date: 24 Oct 1994 01:55:06 GMT Message-ID: <38f45q$d3j@lowell.bellcore.com> Keywords: C, C++, documentation, literate programming To: LitProg@SHSU.EDU In article <3883p6$9dr@urmel.informatik.rwth-aachen.de>, Dirk Sorges wrote: >While there are lots of WEB-like tools, they have some major >disadvantages: > > o Input is not pure C/C++ but a meta-language, and some sort > of weave/tangle tools are needed. Not everyone thinks using a meta-language is a disadvantage. It's not clear why you'd be willing to use a tool to produce documentation but not willing to use a tool to produce source code. Make is good at automating such tasks. > o Most tools are overfeatured Too true. Check out noweb and nuweb. noweb has the smallest command set of any of the LP tools. Both have some HTML support; I'm not sure which is better in that regard. noweb has some automatic cross-reference support for C, but it doesn't really work for C++. >Does anybody know whether there's a tool that provides some of the >features mentioned above and that could be used as a base for >enhancement? You might try to extend noweb if you can overcome your dislike of tangle-like tools. Noweb's author claims it is easy to extend. Some users seem to agree. Where are all the standalone cross-reference tools we had in the 70s? *sigh* Norman ================================================================================ Archive-Date: Fri, 28 Oct 1994 13:13:59 CDT Sender: owner-litprog@SHSU.edu From: trashy@icicle.winternet.com (Barry Schwartz) Reply-To: LitProg@SHSU.edu, trashy@ICICLE.WINTERNET.COM Subject: Re: aut OOP aut LitProg? Date: 28 Oct 1994 17:51:03 GMT Message-ID: <38rdm7$rk8@blackice.winternet.com> To: LitProg@SHSU.EDU In article maavl@cwi.nl (Marc van Leeuwen) writes: ]You can be pretty certain that Don Knuth doesn't read this news group. Nor ]do I think he objects to people using Literate Programming in a different way ]than he does himself. Neither (says he) does he object to people using litprog tools other than WEB and CWEB. If hypermedia are "perfected", then that may take care of a lot of objections that some OOPers have towards litprog. I personally view linear text as the most compelling form of exposition, but perhaps sometimes exposition has to make some compromises. -- Barry Schwartz at MedGraphics trashy@winternet.com ================================================================================ Archive-Date: Sat, 29 Oct 1994 02:31:14 CDT Sender: owner-litprog@SHSU.edu Message-ID: Date: Sat, 29 Oct 94 00:25 PDT To: LitProg@SHSU.edu, pensa@C700-2.SM.DSI.UNIMI.IT Subject: aut OOP aut LitProg? References: <38lar4$6ap@c700-2.sm.dsi.unimi.it> From: Kayvan Sylvan Reply-To: LitProg@SHSU.edu, kayvan@SYLVAN.COM I don't use CWEB, so I won't comment on the CWEAVE-specific problems you were griping about. The way I do C++ code in nuweb is best illustrated by an example. A few general points: I always put one logical module (interface and implementation of a class or set of related classes) in one web file. I have a method that allows me to integrate all the WEB files in my project into one document (with integrated indices) or just print that one module (while I'm developing it). So, I get the expository benefits of a huge monolithic web and the development benefits of having small web files that correspond to my program modules. Here's a sample: %====================================================================== \section{The World Class} The {\tt World} class contains most of the objects in the simulation. Let's look first at the interface to this class. \subsection{World Interface} Here is an overview of the interface to {\tt World}. @o World.h @{// This may look like C, but it's really -*-C++-*- // Copyright (C) 1994, Kayvan Sylvan, Sylvan Associates. All rights reserved. // #ifndef __WORLD_H__ #define __WORLD_H__ #include "Thing.h" class World { public: World(); // constructor ~World(); // destructor void add(Thing*); // Method for adding Thing objects. void tick(); // One unit of time passes. void display(); // Show the user what the world looks like. private: @ }; #endif @| World::add World::tick World::display @} \subsection{World Implementation} The implementation of {\tt World} includes the definition of the class private parts as well as the function definitions that make up the class. @d World Private Parts @{ Thing** list; // List of Thing object pointers. Map map; // Map of the world @| list map @} Now, the implementation of our {\tt World}. @o World.cc @{// Copyright (C) 1994, Kayvan Sylvan, Sylvan Associates. All rights reserved. // static const char rcs[] = "$Id: World.nw,v 1.1 1994/10/24 02:07:20 kayvan Exp $"; #include "World.h" @ @ @ @ @ @} %====================================================================== In this code, as in all my class implementations, the first thing that I write about is the interface. The class's private parts are hidden away and expanded later. Sometimes, I even spend many pages talking about the public members, including various sample usages, before talking about the private members. My rationale is that the published interface (from the standpoint of the user/developer) is more important than the details of the implementation, and it also provides a nice reference section (for myself or others). The nice thing is that the header files that are generated also re-enforce this (by listing public members first). The code that implements the class is put in its own file, with various pneumonic scrap names. All in all, I find that Literate Programming makes it very easy for me to write good object oriented programs that are well documented as a side effect. One caveat: Literate Programming does not take the place of a good Object Oriented Analysis and Design for your system, it merely supplements it. Hope you find this useful, ---Kayvan "The trust and respect of a child is an honor to be earned, not demanded." Kayvan Sylvan | Sylvan Associates | Proud Dad of: kayvan@Sylvan.COM | Training, Consulting | Katherine Yelena (8/8/89) (408) 978-1407 can PGP | NLP Master Practitioner | Robin Gregory (2/28/92) ================================================================================ Archive-Date: Mon, 31 Oct 1994 02:45:28 CDT Sender: owner-litprog@SHSU.edu From: thompson@sun1.coe.ttu.edu Subject: comp.programming.literate FAQ Date: 31 Oct 1994 08:07:25 GMT Message-ID: Reply-To: LitProg@SHSU.edu, thompson@sun1.coe.ttu.edu To: LitProg@SHSU.EDU Archive-name: literate-programming-faq Last-modified: 1994/08/23 Version: 1.1.10 Welcome to the Literate Programming Frequently Asked Questions List ------------------------------------------------------------------- This version was created Tuesday, August 23, 1994, and should considered stale after 90 days. Information contained in this document is the best available at preparation. The original file was dated October 15, 1993 (just for historical purposes). Disclaimer: "This FAQ is presented with no warranties or guarantees of ANY KIND including correctness or fitness for any particular purpose. The author of this document has attempted to verify correctness of the data contained herein; however, slip-ups can and do happen. If you use this data, you do so at your own risk." Copyright 1993, 1994 David B. Thompson. All rights reserved worldwide. Permission is granted to copy this document for free distribution so long as it remains intact and unmodified. For other arrangements, contact the author/maintainer via email: thompson@sun1.coe.ttu.edu. What's New? ----------- + Add Fold2Web entry. + Correct noweb.el entry. (Thanks Dominique!) + Update nuweb.el entry. + Update SchemeWEB entry. + Update WWW and literate programming entry. + Update c2cweb entry. = ====================================================================== * Introduction or "What's this all about?" ------------------------------------------ This document is for new and experienced users of literate programming tools. The purpose is to explain the concept of literate programming and to provide a resource for locating files of interest to literate programmers and those interested in literate programming. The Literate Programming (LitProg) Frequently Asked Questions (FAQ) list is maintained by Dave Thompson, who can be reached at: thompson@sun1.coe.ttu.edu * Preferred mailing address for FAQ related comments/questions. wqdbt@ttacs1.ttu.edu * Forwarded to my pc. Comment and constructive criticism is welcome. Direct flames to /dev/null (or > nul if you're a msdos user! ;-) If you find an error, please report it. I'm particularly interested in establishing the locations of generally available literate programming tools. If you are the author of such a tool and wish to have it included in this list, please send email. Please note this is a work-in-progress. It is *not* complete, and probably will not be complete for some months. Nevertheless, the information contained herein may be useful to some. Use it as it is intended. - ---------------------------------------------------------------------- - Typography ------------ Major sections of the FAQ are divided by double lines (====). Minor sections and other divisions are separated by single lines (----). Major topics use a "* " as a leader. Minor topics use a "- " as a leader. This should simplify searching for topics. = ====================================================================== Table of Contents: ------------------ * Introduction, or "What's this all about?" - Typography * How do I get the FAQ? - Literate Programming FAQ - FWEB FAQ * Is there a newsgroup? (The comp.programming.literate newsgroup) * What internet nodes are of interest to literate programmers? * What is literate programming? * How do I begin literate programming? * What literate programming tools are available and where are they? - APLWEB - AWEB - CLiP - CWEB - FunnelWeb - FWEB - IMPACT - lit2x - Literate Programmer's Workshop (LPW) - MapleWEB - MWEB (Schrod/Detig) - MWEB (Sewell) - noweb - nuweb - ProTeX - RWEB - SchemeWEB - Spidery WEB - WEB - WinWordWEB * Are there other tools I should know about? - C2LaTeX - c2cweb - c2man - cnoweb - Fold2web - FunnelWeb mode - noweb.el - nuweb.el - TIE - Web mode * What other resources are available? - World Wide Web - TeX Resources - Virtual Coursework * Are there any code examples? - Examples included with developer's tools - Cameron Smith's KR-CWEB - Stanford GraphBase * Bibliographies. * How to anonymously ftp. * Acknowledgements. * End notes. = ====================================================================== * How do I get the FAQ? ----------------------- - Literate Programming FAQ -------------------------- You have many ways to get a current copy of this FAQ. One is to use anonymous ftp (if you don't know how, see a later section in this FAQ) to connect to one of the Comprehensive TeX Arvchive Network (CTAN) sites or the Literate Programming Archive and retrieve a copy of the file. Open an ftp connection to one of the CTAN sites and retrieve the file: help/LitProg-FAQ (For more information on CTAN and the literate programming archive, see the section below entitled "Internet Nodes of Interest to Literate Programmers.") An alternative is to use the fileserver at Sam Houston State University (SHSU). Send a message to FILESERV@SHSU.EDU and include in your message: SENDME LITPROG.FAQ The file server will forward a copy of the file to you via email. - ---------------------------------------------------------------------- - FWEB FAQ ---------- Marcus Speh maintains the FWEB FAQ. The current version number is 1.29. It can be retrieved in the same way as this FAQ; either by anonymous ftp or through the SHSU file server. On the SHSU server, the file name is FAQ.FWEB. Invoke your ftp software, open a connection to NIORD.SHSU.EDU [192.92.115.8], attach to the directory FAQ, and transfer the file FAQ.FWEB. Alternatively, send a message to the file server, FILESERV@SHSU.EDU, and include the following text in a one line message: SENDME FAQ.FWEB The file server will send the current version of the file via email. The FWEB FAQ exists in various formats, including HyperText (see other resources below). In Europe, the complete distribution can also be obtained from ftp.desy.de [131.169.10.115] in directory /pub/faq/web/fweb/. It is also available from the literate programming archive (LPA) in the directory LPA/Documentation/faq/fweb (see the references to LPA below for more information). Also, Marcus Speh is looking for someone willing to take over the FWEB FAQ. The text of his email message follows... "Please add to the FWEB FAQ the note that I am looking for someone to take the maintenance of the FAQ over - I am ready to assist in any way whatsoever, including tons of mail, notes for v1.29->v1.30, Texinfo sources, a WWW server and Hypertextification etc." If you're interested, send mail to marcus@x4u2.desy.de and express your willingness to serve. = ====================================================================== * Is there a newsgroup? ----------------------- One of the most important resources is the literate programming newsgroup, comp.programming.literate. You can read this newsgroup using your standard reader. Altenatively, the newsgroup is gated to a mailing list hosted by George Greenwade and Sam Houston State University. You can subscribe by sending mail to the list-server, LISTSERV@SHSU.EDU, and include in the message one line of text: SUBSCRIBE LITPROG "your name in quotes" The list is unmoderated; messages sent to litprog@shsu.edu are automatically distributed to all subscribers and cross-posted to comp.programming.literate. Archives of the mailing list and newsgroup are maintained on niord.shsu.edu [192.92.115.8] in the directory litprog. = ====================================================================== * What internet nodes are of interest to literate programmers? -------------------------------------------------------------- The principal nodes of interest to literate programmers are the Literate Programming Archive (LPA hereafter) and the CTAN (Comprehensive TeX Archive Network). The Literate Programming Archive (LPA) is: Node: ftp.th-darmstadt.de [130.83.55.75] Directory: programming/literate-programming Notes: Fastest response during off-U.S. [yep] business hours. The CTAN sites are: ftp host IP CTAN root Institution and Sponsor ------------------------------------------------------------------------- ftp.tex.ac.uk 134.151.79.32 pub/archive Aston Univ./UK TeX U.G. ftp.dante.de 129.206.100.192 soft/tex DANTE e.V. ftp.shsu.edu 192.92.115.10 tex-archive Sam Houston State Univ. Other nodes and directories of interest include: Node: niord.shsu.edu [192.92.115.8] Directory: various (do some snooping!) Notes: Has a gopher server. Node: ftp.desy.de [131.169.10.115] Directory: pub/web. Various documents, samples, and the FWEB FAQ. Notes: Has a www server, http://info.desy.de:80/ = ====================================================================== * What is Literate Programming? ------------------------------- Literate programming is the combination of documentation and source together in a fashion suited for reading by human beings. In fact, literate programs should be enjoyable reading, even inviting! (Sorry Bob, I couldn't resist!) In general, literate programs combine source and documentation in a single file. Literate programming tools then parse the file to produce either readable documentation or compilable source. The WEB style of literate programming was created by D.E. Knuth during the development of his TeX typsetting software. All the original work revolves around a particular literate programming tool called WEB. Knuth says: The philosophy behind WEB is that an experienced system programmer, who wants to provide the best possible documentation of his or her software products, needs two things simultaneously: a language like TeX for formatting, and a language like C for programming. Neither type of language can provide the best documentation by itself; but when both are appropriately combined, we obtain a system that is much more useful than either language separately. The structure of a software program may be thought of as a web that is made up of many interconnected pieces. To document such a program we want to explain each individual part of the web and how it relates to its neighbours. The typographic tools provided by TeX give us an opportunity to explain the local structure of each part by making that structure visible, and the programming tools provided by languages such as C or Fortran make it possible for us to specify the algorithms formally and unambigously. By combining the two, we can develop a style of programming that maximizes our ability to perceive the structure of a complex piece of software, and at the same time the documented programs can be mechanically translated into a working software system that matches the documentation. Another author (Eric W. van Ammers) wrote me a short article treating his opinions on literate programming. The text follows: First observation on LP About 90% of the disussion on this list is about problems with applying some WEB-family member to a particular programming language or a special documentation situation. This is ridiculous, I think. Let me explain shortly why... Lemma 1: I have proposed for many years that programming has nothing to do with programming langauges, i.e. a good programmer makes good programs in any language (given some time to learn the syntax) and a bad programmer will never make a good program, no matter the language he uses (today many people share this view, fortunately). Lemma 2: Literate Programming has (in a certain way not yet completely understood) to do with essential aspects of programming. Conclusion 1: A LP-tool should be independent of programming language. Lemma 3: It seems likely that the so called BOOK FORMAT PARADIGM [ref. 1] plays an important role in making literate programs work. Lemma 4: There are very many documentation systems currently being used to produce documents in the BOOK FORMAT. Conclusion 2: A LP-tool should be independent of the documentation system that the program author whishes to use. My remark some time ago that we should discuss the generic properties of an LP-tool was based on the above observation. References: [1] Paul W. Oman and Curtus Cook. Typographical style is more than cosmetic. CACM 33, 5, 506-520 (May 1990) Second observation on LP The idea of a literate program as a text book should be extendend even further. I would like to see a literate program as an (in)formal argument of the correctness of the program. Thus a literate program should be like a textbook on mathematicics. A mathematical textbook explains a theory in terms of lemma and theorems. But the proofs are never formal in the sense that they are obtaind by symbol manipulation of a proof checker. Rather the proofs are by so called "informal rigour", i.e. by very precise and unambiguous sentences in a natural language. Eric W. van Ammers Department of Computer Science Wageningen Agricultural University Dreijenplein 2 E-mail: ammers@rcl.wau.nl 6703 HB Wageningen voice: +31 (0)8370 83356/84154 The Netherlands fax: +31 (0)8370 84731 = ====================================================================== * How do I begin literate programming? -------------------------------------- A recommended book is D.E. Knuth's collection of articles (1992) "Literate Programming," Center for the Study of Language and Information, Stanford University, ISBN 0-937073-80-6 (pbk). This book gives insight into Knuth's thoughts as he developed the web system of literate programming (and TeX for typesetting). It does not document methods for literate programming. A recommended book is Wayne Sewell's (1989) "Weaving a Program: Literate Programming in WEB," Van Nostrand Reinhold, ISBN 0-442-31946-0 (pbk). This book focuses on using Knuth's web system. Some talk exists in the newsgroup/mailing list for a Usenet University course in literate programming. I'm sure discussion of this topic will be welcomed. If you are interested, please participate. = ====================================================================== * What literate programming tools are available and where are they? ------------------------------------------------------------------- A significant number of tools for literate programming are available. Most have been ported from their original systems, so support multiple computer platforms. If you are the developer of such a tool, and would like to make the software freely available, please send me email and I'll reply with a form (like those below) for you to fill in. (Or short-circuit the process and kludge a form from below. :-) - ---------------------------------------------------------------------- - APLWEB -------- Developer: Christoph von Basum Version: Unknown Hardware: MSDOS Languages: IBM APL2 and STSC APL Formatter: Plain TeX Availability: Anonymous ftp from: LPA:/apl watserv1.uwaterloo.ca:/languages/apl/aplweb Readme: Unknown Description: None available. Support: Unknown Note: The status of this particular package is unknown. - ---------------------------------------------------------------------- - AWEB ------ Developer: Unknown Version: Unknown Hardware: Unknown Languages: Ada Formatter: Unknown Availability: Anonymous ftp from: LPA:/ada/web Readme: Unknown Description: None available Support: Not supported. - ---------------------------------------------------------------------- - CLiP ------ Developer: E.W. van Ammers and M.R. Kramer Version: Unknown Hardware: Vax/VMS, Unix, and MS-DOS Languages: Any programming language. Formatter: Any formatter (TeX, LaTeX, Troff, Runoff, etc) or any wordprocessor including WYSIWYG systems (Word Perfect, Win Word, Ami Pro, Word, etc.) Availability: Anonymous ftp from: sun01.info.wau.nl:/CLIP/ms_dos MS-DOS version sun01.info.wau.nl:/CLIP/vax_vms VAX/VMS version CTAN:/web/clip LPA:/machines/ms-dos LPA:/machines/vax Readme: With bundle above Description: CLiP does not use explicite commands to perform the extraction process. Rather it recognizes pseudostatemens written as comments in the programming language in question. CLiP distinguishes pseudostatments from ordinary comments because the former comply with a a particular style. This style can be adjusted to suit virtually any programming language. The CLiP approach to LP makes the system extremely versatile. It is independent of programming language and text processing environment. We designed CLiP to be compatible with hypertext systems as well but we have not yet experimented with this form of documentation. Features: + CLiP imposes virtually no limitations on the text-processing system used to produce the documentation. If the text-processor supports these items you can + structure the documentation according to your own taste. + include drawings, pictures, tables etc. + disclose your documentatio my means of X-ref tables, Indexes, Table of contents, Table of tables, Table of figures, etc. + typeset the documented code. + Extracts any number of modules from a maximum of 64 source files. + No pretty-printing. Code from the source files is copied "as is" to the module. + Appearance of code segments in the documentation matches those of the modules to ease the identification of code segements. + Supports partially specified data types. + Comprehensive user manual (preliminary version) and technical description. - No automatic generation of a X-ref table for program identifiers. Support: Bugs, problems and assistance by e-mail: ammers@rcl.wau.nl - ---------------------------------------------------------------------- - CWEB ------ Developer: Silvio Levy and D.E. Knuth Version: 3.0 Hardware: Unix systems (dos and amiga ports available) Languages: C and C++ Formatter: Plain TeX and LaTeX. Availability: Anonymous ftp from: labrea.stanford.edu:/pub/cweb LPA:/c.c++ CTAN:/web/c_cpp/cweb DOS version in CTAN:/web/c_cpp/cwb30p8c DOS version in LPA:/machines/ms-dos Amiga version CTAN:/web/c_cpp/AmigaCWEB Mac port of CTANGLE in LPA:/machines/mac LaTeX support in LPA:/c.c++ Readme: Bundled with above Description: No description provided. Support: Bugs to levy@math.berkeley.edu Note: A fork of CWEB 3.x was developed by Marc van Leeuwen which implements several changes to CWEB. It is available for anonymous ftp from ftp.cwi.nl:pub/cweb. The principle changes are: - Scans include files for typedef definitions - Grammar and formatting rules are well separated, allowing for run-time selection of a rule set (via command line option) - New manual. - ---------------------------------------------------------------------- - FunnelWeb ----------- Developer: Ross N. Williams: ross@guest.adelaide.edu.au Version: Unknown Hardware: MSDOS, Mac, VMS, Sun. Other ports reported. Languages: No restrictions. Formatter: Plain TeX for printing. Otherwise, no restrictions. Availability: Anonymous ftp from: CTAN:/web/funnelweb LPA:/independent ftp.adelaide.edu.au:/pub/funnelweb Readme: With bundle above. Description: FunnelWeb is a production-quality literate-programming tool that emphasises simplicity and reliability. Everything about FunnelWeb, from the simplicity of its language to the comprehensive tutorial in the user's manual, has been designed to make this as simple, as practical, and as usable a tool as possible. Features: + Provides a simple macro preprocessor facility. + Can produce typeset documentation. + Runs on Sun, VMS VAX, Macintosh, PC, and others. + Portable C source code distributed under GNU licence. + Comprehensive user's manual including tutorial. + Programming-language independent. + Can generate multiple output files. + Allows complete control over the output text. + Regression test suite with over 200 tests. + Fully worked example (in /pub/funnelweb/examples). - Requires TeX to produce typeset documentation. - Typesets program code using TT font only. Support: No formal support available. Mailing list maintained with about 50 subscribers. Informal assistance available from mailing list. - ---------------------------------------------------------------------- - FWEB ------ Developer: John A. Krommes Version: 1.30a (1.40 for the experienced, patient, and brave) Hardware: Unix, VMS, and DOS platforms (anything with ANSI C) Languages: C, C++, Fortran-77, Fortran-90, Ratfor, TeX; also, a language-independent mode. Formatter: Plain TeX and LaTeX. Availability: Anonymous ftp from: ftp.pppl.gov:/pub/fweb CTAN:/web/fweb LPA:/fweb DOS version in LPA:/machines/ms-dos Readme: In bundle with above. Description: It also has a well-developed user's manual and its own FAQ (see above). Beginning with 1.40, documentation is maintained in gnu texinfo format. It runs on most platforms: VMS, PC, UNIX, and pretty much anything that the GNU C compiler (GCC) is supported for. Features: + Processes multiple languages during a single run (so one can mix C and Fortran, for example). + Language-independent mode (v1.40). + Ability to turn off pretty-printing (v1.40). + Built-in Ratfor translator. + Built-in macro preprocessor (closely follows ANSI C, with extensions). + A style file that allows the user to adjust many parameters and behavior patterns of FWEB. + Various operator-overloading features that provide additional pretty-printing capabilities to languages such as C++ and Fortran-90. + Numerous miscellaneous features and command-line options. Support: Bug reports and suggestions to krommes@princeton.edu - ---------------------------------------------------------------------- - IMPACT -------- Developer: Timothy Larkin, from Levy/Knuth CWEB 3.1 Version: 1.0 Hardware: Macintosh; requires AppleEvents. Languages: C, C++ Formatter: TeX Availability: CTAN archives Readme: A short readme file is included in the SEA archive. Description: IMPACT implements CTangle from the Levy/Knuth CWEB 3.1. It operates as a foreground program, tangling files selected from the Mac File Picker. Or it can operate in the background, tangling files in response to odoc events sent by other applications, such as editors. Support: I welcome any reports of bugs. The product will be updated as new versions of the CWEB appear. Other features may be added as users suggest them. - ---------------------------------------------------------------------- - lit2x ------- Developer: Unknown Version: Unknown Hardware: Unknown Languages: Unknown Formatter: Unknown Availability: Anonymous ftp from: LPA:/independent Readme: Unknown Description: None available Support: Unknown - ---------------------------------------------------------------------- - Literate Programmer's Workshop (LPW) -------------------------------------- Developer: Norbert Lindenberg Version: 1.1 Hardware: Apple Macintosh Languages: C++, Object Pascal & others Formatter: self-contained WYSIWYG system Availability: Anonymous ftp from: LPA:/machines/mac CTAN:/web/lpw ftp.apple.com:/pub/literate.prog Readme: With bundle above. Also comes with 38-page manual. Description: The Literate Programming Workshop is an environment for the integrated development of program source text and documentation in combined documents. It consists of a WYSIWYG word processor based on a style sheet approach, a mechanism to extract parts of the text in a document, and a project management system that handles multi-document projects. The system is designed to be used in conjunction with the Macintosh Programmer's Workshop: it prepares raw source text for the MPW compilers, accepts MPW error messages, and shows them in the context of the original documents. Automatic indexing and hypertext features allow for easy access to both source text and documentation. LPW is shareware. Support: Bugs, problems, and questions to lpw@aol.com. - ---------------------------------------------------------------------- - MapleWEB ---------- Developer: Unknown Version: Unknown Hardware: Unknown Languages: Maple Formatter: Unknown Availability: Anonymous ftp from: LPA:/maple Readme: Unknown Description: None Support: Unknown - ---------------------------------------------------------------------- - MWEB (Schrod/Detig) --------------------- Developer: Joachim Schrod Version: Unknown Hardware: Unknown Languages: Modula-2 Formatter: Unknown Availability: Anonymous ftp from: LPA:/modula-2 Readme: Unknown Description: None Support: Not supported. - ---------------------------------------------------------------------- - MWEB (Sewell) --------------- Developer: Sewell Version: Unknown Hardware: Unknown Languages: Modula-2 Formatter: Unknown Availability: Anonymous ftp from: LPA:/modula-2 Readme: Unknown Description: None Support: Not supported. - ---------------------------------------------------------------------- - noweb ------- Developer: Norman Ramsey Version: 2.6 Hardware: Unix and DOS platforms. Languages: All programming languages. Formatter: Plain TeX, LaTeX, and HTML (Mosaic) formatters. Availability: Anonymous ftp from: CTAN:/web/noweb LPA:/independent DOS version also in LPA:/machines/ms-dos also bart.kean.edu:/pub/leew Last recourse, use bellcore.com:/pub/norman Readme: With bundle above. Description: noweb is designed to meet the needs of literate programmers while remaining as simple as possible. Its primary advantages are simplicity, extensibility, and language-independence. noweb uses 5 control sequences to WEB's 27. noweb now supports indexing and identifier cross-reference, including hypertext ``hot links'' courtesy of Mosaic. The simple noweb manual is only 2 pages; documenting the full power of noweave and notangle requires another 3 pages. noweb works ``out of the box'' with any programming language, and its formatter-dependent part is a 60-line nawk program. The primary sacrifice relative to WEB is the loss of prettyprinting. Support: email to the author - ---------------------------------------------------------------------- - nuweb ------- Developer: Preston Briggs: preston@cs.rice.edu Version: 0.87 Hardware: Unix systems: Sparcs, RS/6000s, HPs; (!) MSDOS and Amiga. Languages: Any programming language or combination of programming languages. Formatter: Latex Availability: Anonymous ftp from: Unix: CTAN:/web/nuweb DOS: CTAN:/web/nuweb-pc LPA:/independent Amiga: CTAN:/web/nuweb/nuweb_ami Amiga: wuarchive.wustl.edu/pub/aminet Readme: Send mail to preston@cs.rice.edu Description: A single program that takes a web file written in a combination of latex and any programming language(s) and produces a latex file that can be pretty printed and a set of files containing code for compilation/interpretation by the appropriate language processors. Strengths include speed, simplicity, multiple languages, nice indices and cross-references, latex. Doesn't require any special macros or macro files. Drawbacks: latex-dependent, no code pretty printing, harder to make indices than cweb. More good stuff: nice support for make, doesn't reformat source files, so they're easy to debug. Lots of control without too much effort. That is, it doesn't do too much! Future directions... Very little change planned, except perhaps refinements in the indexing software. Support: Hack it yourself or send e-mail to preston@cs.rice.edu - ---------------------------------------------------------------------- - ProTeX -------- Developer: Eitan Gurari Version: 1.1 (AlProTeX 1.2) Hardware: Any platform with TeX (ProTeX is written in TeX) Languages: Any language Formatter: TeX and LaTeX Availability: Anonymous ftp from: ftp.cis.ohio-state.edu : pub/tex/osu/gurari/ LPA:/independent Readme: Unknown Description: There is a book published on using ProTeX, @Book{Gurari:TLD94, author = "Eitan M. Gurari", title = "{\TeX} and {\LaTeX}: Drawing and Literate Programming", publisher = pub-MH, year = "1994", address = pub-MH:adr, bibdate = "Wed Sep 29 17:55:14 1993", acknowledgement = ack-nhfb, } Support: gurari@cis.ohio-state.edu - ---------------------------------------------------------------------- - RWEB ------ Developer: Unknown Version: Unknown Hardware: Unknown Languages: Unknown Formatter: Unknown Availability: Anonymous ftp from: LPA:/reduce Readme: Unknown Description: Web generator in AWK. Support: Unknown - ---------------------------------------------------------------------- - SchemeWEB ----------- Developer: John D. Ramsdell Version: 2.1 Hardware: Unix and DOS platforms Languages: Any dialect of Lisp. Formatter: LaTeX. Availability: The Unix version is in the Scheme Repository and it is available via anonymous ftp from: cs.indiana.edu:/pub/scheme-repository/utl/schemeweb.sh LPA:/lisp CTAN:/tex-archive/web/schemeweb The DOS version is part of the PCS/Geneva Scheme system which is available via anonymous ftp from: cui.unige.ch:/pub/pcs LPA:/machines/ms-dos Readme: In bundle with above. Description: SchemeWEB is a Unix filter that allows you to generate both Lisp and LaTeX code from one source file. The generated LaTeX code formats Lisp programs in typewriter font obeying the spacing in the source file. Comments can include arbitrary LaTeX commands. SchemeWEB was originally developed for the Scheme dialect of Lisp, but it can easily be used with most other dialects. Support: Bug reports to ramsdell@mitre.org. - ---------------------------------------------------------------------- - SpideryWEB ------------ Developer: Norman Ramsey Version: Unknown Hardware: Unix and DOS platforms Languages: Most Algol-like languages, including C, Ada, Pascal, Awk, and many others. Formatter: Plain TeX and latex for text formatters. Availability: Anonymous ftp from: CTAN LPA:/spiderweb Readme: In distribution. Description: A system for building language-dependent WEBs. Spider is frozen; no further development is planned. Support: Bug reports to spider-bugs@oracorp.com. - ---------------------------------------------------------------------- - WEB ----- Developer: Donald Knuth Version: Unknown Hardware: Unknown Languages: Pascal Formatter: TeX (of course! ;-) Availability: Anonymous ftp from: LPA:/pascal Readme: Unknown Description: This is the original software that started it all. The original TeX processor was written in WEB. Support: None known. - ---------------------------------------------------------------------- - WinWordWEB ------------ Developer: Lee Wittenberg Version: Unknown Hardware: Needs Microsoft Word for Windows, v.2.x, and, of course, MS-Windows 3.x. Languages: Any programming language. Formatter: Word for Windows 2.x for text formatting and file maintenance. Availability: Anonymous ftp from: bart.kean.edu:pub/leew LPA:/machines/ms-dos World-Wide Web (WWW) Readme: WORDWEB.DOC in the downloadable package describes the system. Description: WinWordWEB is a set of a Word for Windows macros (plus a paragraph style) that provide a crude literate programming environment. The ``look and feel'' of the system is based on Norman Ramsey's noweb, but can easily be modified to suit individual tastes. Support: None. WinWordWEB was written as a prototype to see if a WYSIWYG literate programming system was possible. It is intended as a jumping off point for future work by others. However, the system is surprisingly usable as it stands, and the author is interested in hearing from users (satisfied and dissatisfied). Anyone interested in actively supporting (and improving) the product should contact the author via email. = ====================================================================== * Are there other tools I should know about? -------------------------------------------- First of all, I'll list some not-quite-literate-programming tools. Some may consider these to be pretty-printers. Others may call them literate programming tools. In any event, they don't seem to be quite in the same category as the tools listed above, so I'll include them here. - C2LaTeX --------- Developer: John D. Ramsdell Version: Unknown Hardware: Unix Languages: C Formatter: LaTeX but it's easy to change the formatter. Availability: Anonymous ftp from omnigate.clarkson.edu:/pub/tex/tex-programs/c2latex. Readme: Absent. Documentation is in the C source for c2latex. Description: C2latex provides simple support for literate programming in C. Given a C source file in which the comments have been written in LaTeX, c2latex converts the C source file into a LaTeX source file. It can be used to produce typeset listings of C programs and/or documentation associated with the program. C2latex produces LaTeX source by implementing a small number of rules. A C comment that starts at the beginning of a line is copied unmodified into the LaTeX source file. Otherwise, non-blank lines are surrounded by a pair of formatting commands (\begin{flushleft} and \end{flushleft}), and the lines are separated by \\*. Each non-blank line is formatted using LaTeX's \verb command, except comments within the line are formatted in an \mbox. Support: Send bug reports to ramsdell@mitre.org. - ---------------------------------------------------------------------- - c2cweb -------- Developer: Werner Lemberg Version: 1.4 Hardware: DOS, OS/2, Unix (gcc) - CWEB source included Languages: C, C++ Formatter: TeX Availability: Anonymous ftp from CTAN:/web/c_cpp/c2cweb Readme: In distribution. Description: c2cweb will transform plain C or C++ code into a CWEB file to get a pretty formatted output. A modified CWEAVE (which transforms the CWEB file into a TeX file, see below) is included also. Support: Werner Lemberg - ---------------------------------------------------------------------- - c2man ------- Developer: Graham Stoney Version: 2.0 patchlevel 26 Hardware: Unix, MSDOS, OS/2. Languages: C Formatter: nroff -man, texinfo (requires yacc/byacc/bison, lex/flex, and nroff/groff/texinfo/LaTeX). Availability: Anonymous ftp from ftp.wustl.edu: /usenet/comp.sources.reviewed/volume03/c2man* ftp.informatik.uni-stuttgart.de: /pub/archive/comp.sources/reviewed/c2man* Readme: See distribution. Description: The primary philosophy here is to use the programming language as far as possible to express the programmer's intentions, and to use comments only when the programming language is not sufficiently expressive. A comment can then become part of the language grammar which is recognised by a "documentation compiler". This tool parses a superset of the programming language and can automatically generate documentation in human-readable form by associating the programmer's comments with the objects in the code by their context. Support: Actively supported; mailing list available: send "subscribe c2man " (in the message body) to listserv@research.canon.oz.au. - ---------------------------------------------------------------------- - cnoweb -------- Developer: Jim Fox Version: 1.4 (January 4, 1991) Hardware: Anything with C and TeX. Languages: C Formatter: Plain TeX. Availability: Anonymous ftp from: CTAN LPA:/c.c++ Readme: Unknown, cnoweb.tex contains documentation. Description: cnoweb is as it's name describes: write C, not web. No tangling or weaving is implemented. Documentation (between standard /* */ delimiteres) is written in TeX. cnoweb provides typesetting of documentation, an table of contents of routines, and pretty-printing of C source. Support: None known. - ---------------------------------------------------------------------- - Fold2Web ---------- Developer: Bernhard Lang Version: V0.8 Hardware: MSDOS Languages: All (must allow comment lines) Formatter: LaTeX Availability: Anonymous ftp from: kirk.ti1.tu-harburg.de (134.28.41.50) /pub/fold2web/readme /pub/fold2web/fold2web.zip Readme: In distribution Description: The idea behind the Fold2Web tool is the following: A programmer can write his program source with a folding editor and later map the folded source files automatically to WEB-files. The generated WEB-files can then be modified by inserting required documentations. The advantage by starting program developement with original sources is to get short design cycles during the compile/debug steps. By using a folding editor the global structuring information can be already captured in folds during this developement phase. Fold information is typically stored in comment lines and thus will not affect the efficiency of the compile/debug design cycle. Some folding editors and a folding mode for the emacs are available (e.g. see our FUE folding editor for MSDOS machines which is a modified micro emacs. Pick it at kirk in directory /pub/fold2web). After reaching a stable version of a program source its time to convert the source file to a WEB-file and do the program documentation. Fold2Web is written to convert folded source text of any programming language to nuweb files. The folded structure is kept by mapping folds to scraps. Fold markers which differ between languages due to different ways of specifying comments can be configured for each language. Good results can also achived when given but poor documented program sources have to be modified. Such sources can be folded using a folding editor to extract the global structures. This offers a global view to the program structures and help to understand its functionality. Furthermore the program code is not affected, only comment lines are inserted. Once folded the program source can be automatically translated to a WEB document using the above tool. Support: email to lang@tu-harburg.d400.de - ---------------------------------------------------------------------- - Funnelweb Mode ---------------- Developer: Daniel Simmons Version: Unknown Availability: Litprog archives (was in email) Anonymous ftp from: ftp.imada.ou.dk Description: The other day I did a quick hack to nuweb.el as included with the nuweb distribution so as to make a funnelweb-mode.el. I've only used it briefly, and I'm sure that it can be improved quite a bit. I've been thinking about adding support for folding on sections, a pull-down menu to select macro definitions (like the recent functions posted to gnu.emacs.sources for a C function definition pull-down menu) and some kind of tags support for funnelweb. Support: Unknown - ---------------------------------------------------------------------- - noweb.el ---------- Developer: Bruce Stephens Version: Unknown. Availability: LitProg archives (in an email message). Description: This is a very simple mode I just hacked up. There's a lot wrong with it, but I thought others may be interested, even as it stands. It *requires* text properties, and assumes those used in GNU Emacs 19.22; it'll quite likely work with Lucid Emacs, but I haven't tried it. I use it with auctex8.1 and cc-mode 3.229, both of which are loaded separately (I think my emacs is dumped with them, in fact). The idea is to have one mode (which calls itself c-mode, but actually has LaTeX-mode keybindings) generally (this means that the code is hilighted nicely), and have the code chunks use a different keymap. Support: Email to bruce@liverpool.ac.uk - ---------------------------------------------------------------------- - nuweb.el ---------- Developer: Dominique de Waleffe Version: 1.99 Availability: Anonymous ftp from: LPA CTAN Description: Provides a major mode extending Auctex for editing nuweb files. Main features (in 2.0): - Edit scrap bodies in a separate buffer in a different mode (selected using emacs defaults for files, specific indication -*-mode-*-, or a buffer-local variable) - Extends Auctex commands so that nuweb is called before LaTeX, - Easy navigation on scrap definition and use points. - Now creates an imenu (C-M-mouse1) with user index entries, macro definition positions and file definition positions. Support: Email to ddw@sunbim.be - ---------------------------------------------------------------------- - TIE ----- Developer: Unknown Version: Unknown Hardware: Unknown Availability: Anonymous ftp from: LPA:/Tools Readme: Unknown Description: This software merges change files. Support: Unknown - ---------------------------------------------------------------------- - Web mode ---------- Developer: Bart Childs Version: Unknown Tools supported: web, fweb, cweb, funnelweb Availability: Anonymous ftp from ftp.cs.tamu.edu:pub/tex-web/web/EMACS.web-mode thrain.anu.edu.au:pub/web/EMACS.web-mode Description: This version works with versions 18 and 19 of Emacs to be best of my knowledge. I have cleaned up a number of documentation items ... In the same directory is wm_refcard.tex which is an edited version of the famous one to include some web-mode commands. The files limbo* are related to its use and notice that half them have an uppercase L in them for LaTeX. The setup is based upon the fact that we (I am not alone here) primarily use FWEB for C and Fortran programming. We are using version 1.40 of FWEB although John Krommes warns that it is not mature and the manual is not yet updated. The info files are! We are using LaTeX almost exclusively. That will likely change and we will revert to version 1.30 if the final form of 1.40 cannot return to the simple section numbers and avoid the HORRIBLE LATEX 0.1.7.2.4.6 type section numbers. Support: Unknown = ====================================================================== * What other resources are available? ------------------------------------- - World Wide Web ---------------- An untapped resource (by me anyway ;-) is the World Wide Web. Marcus Speh has expended considerable effort in this regard. If you're connected to WWW, then access: http://info.desy.de:80/user/projects/LitProg.html If you aren't connected to WWW, telnet to info.cern.ch and explore. You can reach Marcus' literate programming pages by typing: go http://info.desy.de:80/user/projects/LitProg.html Help for people who have only Email and neither WWW nor telnet, can be obtained by Email from TEST-LIST@INFO.CERN.CH by sending a message, SEND , for example, SEND http://info.desy.de:80/user/projects/LitProg.html to retrieve the LitProg library page. A help file can be retrieved by sending a message to the list server above with the text HELP in the body of the message. Instructions will be returned by email. For literate programming documents, you can try anonymous ftp to ftp.desy.de [131.169.10.115] and get the file: /pub/userWWW/projects/Announce/LitProg.txt - ---------------------------------------------------------------------- - TeX Resources --------------- Another resource of interest to literate programmers is the info-tex mailing list. If you're using (La)TeX as your typsetting system and have access to internet, then you should investigate this mailing list. Mail list service is available through the SHSU list-server. To subscribe, send a message to LISTSERV@SHSU.EDU, and include in the message one line of text: SUBSCRIBE INFO-TEX "your name in quotes" The list is unmoderated; messages sent to info-tex@shsu.edu are automatically distributed to all subscribers and cross-posted to comp.text.tex. Archives of the mailing list and newsgroup are maintained on niord.shsu.edu [192.92.115.8] in the directory info-tex. Another reason the TeX resources should be important is that so many of the literate programming tools rely on either plain TeX or LaTeX as their text formatter. (La)TeX software systems exist for most computing platforms. These systems can be found on CTAN and other major archive sites. Use archie to find them or simply ftp to one of the CTAN sites and browse. - ---------------------------------------------------------------------- - Virtual Coursework -------------------- Marcus Speh plans an introductory course on Literate Programming on the Internet, part of the first semester of "Global Network Academy" [GNA], a non-profit corporation incorporated in the state of Texas, affilated with the Usenet University project. The texts/sample programs for this class will be made available via the World-Wide Web. A special room on GNA Virtual Campus will be staffed by a consultant in one to two hour shifts. Students with questions can telnet to the virtual campus and ask questions of the staff there. If you are interested in registering for the course either as a student or as a consultant, please contact marcus@x4u.desy.de. You will receive a standard reply message; no further action will be taken until June 94. Interested parties can check the hypertext notes for the completed C++ Course done in a similar fashion, at URL http://info.desy.de:80/pub/uu-gna/html/cc/index.html [Editor's note: Because of workload, Marcus requests that email inquiries be limited to a statement of interest for either a student or consultant position until June 1994.] = ====================================================================== * Are there any code examples? ------------------------------ Examples of web programs are included with the FWEB, CWEB, and noweb distributions. nuweb is written in itself. Cameron Smith converted the K&R calculator program into a literate program. It can be retrieved by anonymous ftp from: niord.shsu.edu [192.92.115.8] directory kr-cweb-sample as krcwsamp.zip or from LPA/Documentation Ross Williams has released a funnelweb example. You can retrieve this file from node ftp.adelaide.edu.au [129.127.40.3] as /pub/funnelweb/examples/except.* This file should be on CTAN as well. Lee Wittenberg has posted a few litprog examples. They are available via anonymous ftp from: bart.kean.edu:/pub/leew/samples.LP The Stanford GraphBase is a large collection of programs by Don Knuth for doing all kinds of computations and games with graphs; it is written in (Levy/Knuth) CWEB. More details in the distribution. It is available via anonymous ftp from: labrea.stanford.edu:/pub/sgb = ====================================================================== * Bibliographies ---------------- Nelson Beebe has collected an extensive bibliography treating literate programming. His work is available for anonymous ftp from ftp.math.utah.edu [128.110.198.2] in directory /pub/tex/bib as files: litprog.bib litprog.ltx litprog.twx. Although I have not verified this, LPA is an alternate source for these files. Note that they are updated frequently (Nelson says several times each week), so be sure to get a fresh copy before extensive use. Joachim Schrod indicates that these files may be updated daily and can be retrieved via anonymous ftp at LPA/documentation. = ====================================================================== * How to anonymously ftp ------------------------ Pretty much everything mentioned here is available by anonymous FTP. FAQ lists cross-posted to news.answers and rec.answers can be gotten from rtfm.mit.edu [18.181.0.24], under /pub/usenet/news.answers or under /pub/usenet/more.specific.group.name "anonymous FTP" is just a way for files to be stored where anyone can retrieve them over the Net. For example, to retrieve the latest version of the literate programming FAQ, do the following: > ftp rtfm.mit.edu /* connect to the site; message follows */ > anonymous /* type this when it asks for your name */ > /* type your address as the password */ > cd /pub/usenet /* go to the directory you want to be */ > cd comp.programming.literate /* one level down (no slash). */ > dir /* look at what's there */ > get literate-progamming-faq /* get the file; case-sensitive */ > quit /* stop this mysterious thing */ If your FTP program complains that it doesn't know where the site you want to use is, type the numerical address instead of the sitename: > ftp 18.181.0.24 /* connect with numerical address */ If you don't have ftp access, send e-mail to mail-server@rtfm.mit.edu with the single word "help" in the body of the message. Getting binary files (executables, or any compressed files) is only slightly more difficult. You need to set binary mode inside FTP before you transfer the file. > binary /* set binary transfer mode */ > ascii /* set back to text transfer mode */ FAQs and spoiler lists are generally ascii files; everything else is generally binary files. Some common extensions on binary files in archive sites are: .Z Compressed; extract with uncompress .tar.Z Compressed 'tape archive'; uncompress then untar or tar -xvf .gz or .z Gnu gzip; use gunzip (available from prep.gnu.ai.mit.edu) .sit (Mac) StufIt archive .zip Extract with Zip or Unzip .zoo Yet another archive/compress program .lhe (Amiga) ? .lzh Lha archive program. .arj (PC) Arj archive program. .exe (PC) Sometimes self-extracting archives-just execute them. .uue or .UUE Transfer as text file; use uudecode to convert to binary .hqx (Mac) BinHex format; transfer in text mode Generic help can be found in the FAQs of comp.binaries. for how to transfer, extract, and virus-check binary files. (At rtfm.mit.edu) If you can't FTP from your site, use one of the following ftp-by-mail servers: ftpmail@decwrl.dec.com ftpmail@src.doc.ic.ac.uk ftpmail@cs.uow.edu.au ftpmail@grasp.insa-lyon.fr For complete instructions, send a message reading "help" to the server. If you don't know exactly what you're looking for, or exactly where it is, there are programs and servers that can help you. For more info, send e-mail to mail-server@rtfm.mit.with with the body of the message reading send usenet/news.answers/finding-sources Thanks to Aliza R. Panitz (the "buglady") for this text. I copied it verbatim from her post on faq-maintainers with only minor modifications. = ====================================================================== * Acknowledgements ------------------ This document would not have happened without the help of many people. Among them are Marcus Speh, George Greenwade, Rob Beezer, Joachim Schrod, Piet van Oostrum, and Ross N. Williams. A special thanks to Aliza R. Panitz for the text describing how to execute an anonymous ftp for files of interest. Any omissions from these acknowledgements should be considered an act of stupidity on my part. Of course, the authors of literate programming tools mentioned above all play a vital role in the vitality of literate programming. Furthermore, participants in the comp.programming.literate newsgroup (and associated mailing list) all contributed in various fashions. Thank all of you. = ====================================================================== * End notes ----------- This document will continue to evolve. I'm planning on adding entries for additional literate programming tools and will expand the sections on examples as more examples become available. Tools I will include are WEB (the original pascal version) for starters. Others will be added as I find and document them. Omission of a particular tool should not be considered a snub in any sense--simply an error or oversight on my part. = End of File ========================================================== ================================================================================ Archive-Date: Mon, 31 Oct 1994 03:56:40 CDT Sender: owner-litprog@SHSU.edu From: cnas30@ccsun.strath.ac.uk (E. St. John-Olcayto) Subject: cweb, LaTeX Date: 31 Oct 1994 09:43:41 GMT Message-ID: <392e8d$m5g@rockall.cc.strath.ac.uk> Reply-To: LitProg@SHSU.edu, cnas30@ccsun.strath.ac.uk To: LitProg@SHSU.EDU Can anybody out there help me. I'm using cweb and Joachim schrod's style file for use with LaTeX. Unfortunately. when I try to go through the examples given with the style file package, LaTeX2e (the version I use) returns the error: cweb.cls file not found What is this file and where can it be found? --- ------------------------------------------------------------------------------ | Ender St. John-Olcayto | "The concept of a | | Industrial Control Centre | fuzzy state needs | | Department of Electronic and Electrical Engineering | to be clarified" | | University of Strathclyde | | | Scotland | Fuzzy Sets and | | Tel.:+44 41 552 4400 x2666 | Systems | | Fax.:+44 41 553 1232 | | | | Dubois and Prade | | Email : cnas30@ccsun.strath.ac.uk (preferred) | | | or : sender@icu.strath.ac.uk | | ------------------------------------------------------------------------------ ================================================================================ Archive-Date: Mon, 31 Oct 1994 04:27:45 CDT Sender: owner-litprog@SHSU.edu Message-ID: <199410311026.AA28851@noc.BelWue.DE> From: Aaron "Optimizer" Digulla Reply-To: LitProg@SHSU.edu, digulla@FH-KONSTANZ.DE Subject: Re: cweb, LaTeX To: LitProg@SHSU.edu, cnas30@ccsun.strath.ac.uk Date: Mon, 31 Oct 94 11:21:26 MEZ > Can anybody out there help me. > I'm using cweb and Joachim schrod's style file for use with LaTeX. > Unfortunately. when I try to go through the examples given with the > style file package, LaTeX2e (the version I use) returns the error: > > cweb.cls file not found > > What is this file and where can it be found? Have you run "cweb.ins" (or a similar file *.ins through) latex ? It should have generated that file. If you did, look for the file and remember to add the path to TEXINPUTS. -- Aaron "Optimizer" Digulla. Author of XDME "(to) optimize: Make a program faster by improving the algorithms rather than by buying a faster machine." ================================================================================ Archive-Date: Mon, 31 Oct 1994 06:02:40 CDT Sender: owner-litprog@SHSU.edu From: schrod@iti.informatik.th-darmstadt.de (Joachim Schrod) Reply-To: LitProg@SHSU.edu, schrod@ITI.INFORMATIK.TH-DARMSTADT.DE Subject: Re: cweb, LaTeX Date: 31 Oct 1994 11:54:12 GMT Message-ID: <392lt4$16k5@rs18.hrz.th-darmstadt.de> To: LitProg@SHSU.EDU In article <392e8d$m5g@rockall.cc.strath.ac.uk>, cnas30@ccsun.strath.ac.uk (E. St. John-Olcayto) writes: > Can anybody out there help me. > I'm using cweb and Joachim schrod's style file for use with LaTeX. > Unfortunately. when I try to go through the examples given with the > style file package, LaTeX2e (the version I use) returns the error: > > cweb.cls file not found > > What is this file and where can it be found? Nowhere. cweb.sty has not (yet) been converted to a full LaTeX2e class. You have to use it in compatibility mode. I.e., instead of \documentclass{cweb} use \documentstyle{cweb} i.e., do exactly as described in the documentation... Don't believe the people that tell you that you can change every \documentclass to a \documentstyle and it will work afterwards, that's simply not true. If you look at the examples of those people you'll recognize that they all use the standard documentstyles. While it is very easy to transform a style option to a package, the proper transformation of a full style to a class is not done as fast. The conversion of my LaTeX macro packages to LaTeX2e has a high priority on my TODO-list, so I hope that it won't be too long until I'll release them. No promises, though; I have a real job to do... :-( Joachim -- =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= Joachim Schrod Email: schrod@iti.informatik.th-darmstadt.de Computer Science Department Technical University of Darmstadt, Germany ================================================================================ Archive-Date: Mon, 31 Oct 1994 12:59:42 CDT Sender: owner-litprog@SHSU.edu Date: Mon, 31 Oct 94 13:59:24 EST From: Lee Wittenberg Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET To: LitProg@shsu.edu, pensa@c700-2.sm.dsi.unimi.it Subject: Re: aut OOP aut LitProg? Message-ID: Giovanni MenoZero Pensa writes: > Well, I have a question... > I program in C++ and I use CWEB. No REAL problems. But... > > With LitProg you can declare your vars were you want? > Also with C++. > (the problem is that with CWEB's philosophy, the wars are moved > at the beginning, sigh) In this case, I think you're mistaken. Although the vars are moved to the beginning, this is only in the tangled output, which is meant to be read by a compiler, rather than a human being. Humans should be concerned only with the variables' locations in the woven web. > You know, I'm not versus WEB. Really. I'm just saying that some > things are useless (and sometimes are a real problem) and that > maybe I need others features. (I don't know what. Yet.) [Example omitted.] > That's (more or less) how I work. > The things I don't like: > - I'd like "Point& p" more than "Point &p". You need to modify CWEAVE's production rules to do this (it isn't as hard as it looks, but it ain't easy, either). Personally, I agree with your preference, but I see it as similar to the big-endian vs. little-endian debate: Both sides have supporting arguments, but if we could just flip a coin and pick one as a ``standard,'' we'd save a lot of time (and money). > - I'd like that after "public:" CWEB put a NewLine. Again, you can modify the productions. This one should be quite easy. > Ok, I know I'm confused and confusing. I just want to know your opinion. > "How do you write (small) classes with C++ and CWEB?" Pretty much the same way I write large ones. A skeleton: class blah { @<|blah|'s private members@>@; public: @/ @q Yes, I prefer this, too @> @<|blah|'s public members@>@; }; And so on... > "Is your style better than mine?" Just different. > "Do you think there are some problems, too?" Not major ones. -- Lee ------------------------------------------------------------------------ Lee Wittenberg | Halavah is a form of pie, and it has a Computer Science Department | specific gravity of 3.1416 and a specific Kean College of New Jersey | heat of .31416 Union, NJ 07083 | USA | -- D. E. Knuth | "The Potrzebie System of Weights leew@pilot.njin.net | and Measures" (1957) ------------------------------------------------------------------------ ================================================================================ Archive-Date: Mon, 31 Oct 1994 17:37:43 CDT Sender: owner-litprog@SHSU.edu From: schrod@iti.informatik.th-darmstadt.de (Joachim Schrod) Reply-To: LitProg@SHSU.edu, schrod@ITI.INFORMATIK.TH-DARMSTADT.DE Subject: Contents of the LitProg Archive (monthly posting) Date: 1 Nov 1994 00:20:05 +0100 Message-ID: <393u35INNdu3@spice.iti.informatik.th-darmstadt.de> To: LitProg@SHSU.EDU # literate-programming/Contents 05 Oct 94 -*- 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 -- source independent wordprocessor. Hypertext -- for DOS machines/ms-dos integration possible -- for VMS machines/vms CTWILL c.c++ CWEAVE w/ mini indexes [DEK] unfinished, alpha quality CWEB (Levy/Knuth) C++, ANSI C, K&R C -- source c.c++ -- Amiga port machines/amiga -- Atari TOS port machines/atari-tos an old version [2.4 p5b] -- DOS port machines/ms-dos -- Mac port machines/mac -- Mac CTANGLE machines/mac Impact: CTANGLE & Apple-Events 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 -- MS-Windows port machines/ms-windows Impact machines/mac CTANGLE & Apple-Events Knit pascal not supported any more lit2x independent [????] from Glasgow LPW machines/mac Literate Programming Workshop CAVEAT: Shareware! MapleWEB 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 nuweb lean system, written in C -- source independent -- Amiga port machines/amiga -- DOS port machines/ms-dos ProTex independent WEB system based on TeX RWEB spiderweb for Reduce smlweb spiderweb for Standard ML 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 Literate Documentation Systems ------------------------------ (or LitDoc systems for short): Tools that do not support refinements but enable the use of usual document preparation systems (e.g., LaTeX) in program comments. cnoweb c.c++ doc package /pub/tex/latex CAVEAT: No LitProg A directory! oriented towards TeX code; part of the LaTeX2e distrib. MAKEPROG independent is here for my own convenience :-) SchemeWEB lisp wbuild /pub/X11/other/fwf CAVEAT: No LitProg A directory! creating new X widget classes -- The Literate Programming Archive, or LitProg Archive for short, resides at ftp.th-darmstadt.de [130.83.55.75], directory pub/programming/literate-programming/. =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= Joachim Schrod Email: schrod@iti.informatik.th-darmstadt.de Literate Programming Archive, maintainer Technical University of Darmstadt, Germany ================================================================================ Archive-Date: Mon, 31 Oct 1994 17:37:48 CDT Sender: owner-litprog@SHSU.edu From: schrod@iti.informatik.th-darmstadt.de (Joachim Schrod) Reply-To: LitProg@SHSU.edu, schrod@ITI.INFORMATIK.TH-DARMSTADT.DE Subject: Diff to Contents of the LitProg Archive (monthly posting) Date: 1 Nov 1994 00:20:07 +0100 Message-ID: <393u37INNdu5@spice.iti.informatik.th-darmstadt.de> To: LitProg@SHSU.EDU *** Contents Sat Oct 1 00:20:12 1994 --- /common/ftp/pub/programming/literate-programming/Contents Wed Oct 5 11:59:11 1994 *************** *** 1,3 **** ! # literate-programming/Contents 04 May 94 -*- Indented-Text -*- #------------------------------------------------------------ --- 1,3 ---- ! # literate-programming/Contents 05 Oct 94 -*- Indented-Text -*- #------------------------------------------------------------ *************** *** 30,33 **** --- 30,35 ---- -- for DOS machines/ms-dos integration possible -- for VMS machines/vms + CTWILL c.c++ CWEAVE w/ mini indexes [DEK] + unfinished, alpha quality CWEB (Levy/Knuth) C++, ANSI C, K&R C -- source c.c++ -- The Literate Programming Archive, or LitProg Archive for short, resides at ftp.th-darmstadt.de [130.83.55.75], directory pub/programming/literate-programming/. =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= Joachim Schrod Email: schrod@iti.informatik.th-darmstadt.de Literate Programming Archive, maintainer Technical University of Darmstadt, Germany ================================================================================ Archive-Date: Mon, 31 Oct 1994 17:37:55 CDT Sender: owner-litprog@SHSU.edu From: bglanvil@cln.etc.bc.ca (Brook Glanville) Subject: Fractals Message-ID: <1994Oct31.225749.8295@news.etc.bc.ca> Reply-To: LitProg@SHSU.edu, bglanvil@cln.etc.bc.ca (Brook Glanville) Date: Mon, 31 Oct 1994 22:57:49 GMT To: LitProg@SHSU.EDU I am a grade 9 student in Williams Lake, British Columbia. I like mathematics and am presently working on a science fair project regarding fractals. If anyone has any information on writing fractals or any information in general, please let me know. Thanks.