Archive-Date: Mon, 18 Oct 1993 10:38:52 CST Sender: LP-Mgr@SHSU.edu From: johnson@cs.uiuc.edu (Ralph Johnson) Reply-To: LitProg@SHSU.edu, johnson@CS.UIUC.EDU Subject: Re: Interactive literate programming Message-ID: Date: Mon, 18 Oct 1993 14:57:30 GMT To: LitProg@SHSU.EDU > >There is a fairly nice system for the Apple Macintosh. It's called the > >"Literate Programmer's Workshop" and you'll find it at ftp.apple.com, > >pub/literate.prog and doubtlessly in other places. >Does this require MPW? LPW will convert your document into a set of files that you can feed to MPW, and it will take error messages from MPW and show you where they came from in your document. So, LPW seems to require MPW to actually compile programs, but it doesn't require it just to print documentation or to edit files. There is a humorous comment in their documentation where they say that LPW will run on any version of Mac O.S. and requires 600 K, but that it is not very useful without MPW, which requires System 7 and 4 megabytes. This seems like a problem that needs to be fixed! -Ralph ================================================================================ Archive-Date: Mon, 18 Oct 1993 10:39:58 CST Sender: LP-Mgr@SHSU.edu From: warren@math.psu.edu (Warren Wood) Reply-To: LitProg@SHSU.edu, warren@MATH.PSU.EDU Subject: Re: Interactive literate programming Date: 18 Oct 93 10:37:38 Message-ID: To: LitProg@SHSU.EDU In article johnson@cs.uiuc.edu (Ralph Johnson) writes: >There is a fairly nice system for the Apple Macintosh. It's called the >"Literate Programmer's Workshop" and you'll find it at ftp.apple.com, >pub/literate.prog and doubtlessly in other places. i got a copy of it. It *is* a nice system. The basic idea behind it is a lot different from Web-like systems. You write a document using a WYSIWYG editor. Every section has a different "style" that is defined by a style sheet. The document is designed to be readable by humans. You get the machine-readable documents by selecting sections of particular styles and running them through various translators. This is all automatic, and it looks like you only have to worry about the details if you are trying to make it work with a new language. You have to have a Mac to read the documentation, which is written in itself, of course. But I'd advise anyone interested in these kinds of systems to find a Mac and at least try to print off the documentation. -Ralph Johnson Does this require MPW? ================================================================================ Archive-Date: Mon, 18 Oct 1993 10:41:29 CST Sender: LP-Mgr@SHSU.edu From: schrod@iti.informatik.th-darmstadt.de (Joachim Schrod) Reply-To: LitProg@SHSU.edu, schrod@ITI.INFORMATIK.TH-DARMSTADT.DE Subject: Usage of RCS in *WEB Documents (was Re: Some thoughts) Date: 18 Oct 1993 11:22:23 GMT Message-ID: <29tu9gINNh8k@rs18.hrz.th-darmstadt.de> To: LitProg@SHSU.EDU In article <1993Oct14.160744.252@kocrsv01.delcoelect.com>, c21vc@kocrsv01.delcoelect.com (Venkataraman Chandrasekhar) described his problems in the usage of RCS & *WEB. I've worked on this a few months ago, and I can release the results if there is enough interest. But first a few comments on this article, I don't quote fully due to its length. -- I don't agree that information about the history of a program are ``almost always of short term value, if any.'' For me, they are an integral part of any software development. (Those who don't know their past are condemned to repeat it...) How many times has an error been repeated because it was `obviously' the right way to do it; and nobody knew that it was done before already? -- ``I find it annoying that I have to thumb through multiple pages of these before I get to the first source line.'' I agree with you -- put them in an appendix at the end and put a reference to this appendix at the start of your document. -- [On the work with RCS]: ``Each time, a source file is checked back in, people put a line or two of comments.'' This is a major problem. RCS logs like `Fixed.' (from your example) are useless. But RCS encourages these types of logs since it simply reads them from the standard input. In our experiences providing an editor for typing in log messages leads to longer, better phrased log messages. So, what did we do? -- We changed RCS. In our version, it's possible to . define the used RCS keywords in configuration file(s). I.e., one can use $XConsortium$ instead of $Id$... ;-) . define the way the revision log is output. E.g., one can output it as \begin{RCSlog} $Log: rcs.doc,v $ \Revision 1.2 1993/09/08 15:49:00 schrod Used canonical names for category codes. ... \end{RCSlog} Of course, it isn't difficult to write an appropriate environment to typeset this. . use an editor for the input of the Log text. . have a better approximation of the comment leader. -- I wrote a new rcs style option. This style option is upward compatible both to the one by Piet v.Oostrum and to a previous revision from me. (It was a Bad Thing anyhow that there were two incompatible style options with the same name.) This style option supports typesetting of revision logs, if used together with the new RCS. Why didn't we distribute it yet? -- We need a smoother integration into CVS, we're not interested in RCS per se. But if there is enough interest, I can make a pre-release ready. -- Joachim =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= Joachim Schrod Email: schrod@iti.informatik.th-darmstadt.de Computer Science Department Technical University of Darmstadt, Germany ================================================================================ Archive-Date: Mon, 18 Oct 1993 10:41:40 CST Sender: LP-Mgr@SHSU.edu From: lynbech@daimi.aau.dk (Christian Lynbech) Reply-To: LitProg@SHSU.edu, lynbech@DAIMI.AAU.DK Subject: Re: Revision Control Date: 18 Oct 1993 09:10:38 GMT Message-ID: <29tmie$3pr@belfort.daimi.aau.dk> To: LitProg@SHSU.EDU It wasn't exactly clear to me what RCS style Lee Wittenberg was referring to, so I thought I would post the most excellent rcs.sty written by Piet van Oostrum. Not necessarily the one true way, but nice if you haven't something of the sort in advance. Check out the stuff below my signature. The way I use it, is to mark each page with state, revision number and date in the footers, using fancyheadings.sty ------------------------------------------------------------------------------ Christian Lynbech | Hit the philistines three times over the office: R0.32 phone: 5034 | head with the Elisp reference manual. email: lynbech@daimi.aau.dk | - petonic@hal.com (Michael A. Petonic) ------------------------------------------------------------------------------ %% %% REVISION CONTROL %% Piet van Oostrum, Dept of Computer Science, Utrecht University, %% Padualaan 14, P.O. Box 80.089, 3508 TB Utrecht, The Netherlands. %% Telephone: +31 30 531806 Uucp: uunet!mcsun!ruuinf!piet %% Telefax: +31 30 513791 Internet: piet@cs.ruu.nl %% %% To use the RCS field XXX (e.g. XXX=Header or XXX=Date) in a (La)TeX %% document include %% \RCS$XXX$ %% This is expanded by RCS into \RCS$XXX: $ %% The TeX macro above defines (globally) \RCSXXX to be . %% If the field XXX is not RCS-expanded \RCSXXX is defined as the null string. %% %% Exception: %% For XXX=Date, if the macro \today is defined, the RCS date is %% reparsed into the format defined by \today, with \year, \month and \day %% bound to the values in the RCS Date field. This allows you to get a %% language-dependent date format, e.g. by using dutch.sty, german.sty etc. %% The time part is put into the macro \RCSTime. The original RCS date can %% be found in \RCSRawDate. %% Also the default value for \RCSDate is the value of \today. %% %% Note: This kind of special-casing can be applied to other fields also by %% defining a macro \RCS@XXX. This macro will be called with the field %% as argument and should do all the work (including defining \RCSXXX). %% %% N.B: %% Verbatim insertion can not be done in this way. Just use \verb$XXX$, or %% put $XXX$ in a verbatim environment. And of course you can put a field %% in comment (useful for the Log entry). \def\RCS$#1${\RCS@#1:$} \def\RCS@#1:#2${% {\def\temp@{#2}% \ifx\temp@\empty \RCS@@#1:$% \else \RCS@@@#1:#2$% \fi} } \def\RCS@@#1:#2${\RCS@@@#1: #2 :$} \def\RCS@@@#1: #2 :${% \expandafter\ifx\csname RCS@#1\endcsname\relax \expandafter\gdef\csname RCS#1\endcsname{#2} \else \csname RCS@#1\endcsname{#2} \fi } \def\RCS@Date#1{% \gdef\RCSRawDate{#1}% \ifx\today\relax \gdef\RCSDate{#1}% \else \ifx\temp@\empty %Note: temp@ still valid from the \RCS@ call \gdef\RCSDate{\today}% \else \RCS@@Date #1$% \fi \fi } \def\RCS@@Date #1/#2/#3 #4${ \gdef\RCSTime{#4}% \def\year{#1}\def\month{#2}\def\day{#3}% Note: we are in a group by RCS@ \xdef\RCSDate{\today} } \def\RCSTime{} ================================================================================ Archive-Date: Mon, 18 Oct 1993 13:17:25 CST Sender: LP-Mgr@SHSU.edu From: d.love@dl.ac.uk (Dave Love) Reply-To: LitProg@SHSU.edu, d.love@DL.AC.UK Subject: Re: Some thoughts Date: 18 Oct 1993 17:22:28 GMT Message-ID: To: LitProg@SHSU.EDU >>>>> On Fri, 15 Oct 93 16:08:34 +0100, coates@spectro.jussieu.fr said: coates> current LitProg tools are certainly geared towards telling coates> you how the code works, as opposed to why it went wrong after coates> it was working in the first place. The `doc' system for TeX does include a `\changes' feature to record brief information about what was changed when and why; this is indexed by version number at the end. Major explanations of this sort of thing probably belong in the commentary, though. ================================================================================ Archive-Date: Mon, 18 Oct 1993 13:40:14 CST Sender: LP-Mgr@SHSU.edu From: rml@genesis.MCS.COM (Ryan Lee) Reply-To: LitProg@SHSU.edu, rml@GENESIS.MCS.COM Subject: compu transcript Date: 18 Oct 1993 12:41:10 -0500 Message-ID: <29ukfm$moj@genesis.MCS.COM> To: LitProg@SHSU.EDU Could someone tell me what sorts of programming contests/ activities/etc. I could put on my transcript for college? Although I don't plan to major in computer sciences, I am a computer enthusiast who programs intermediately with C and will likely remain involved with computers. But unfortunately my high-school offers very few computer science courses and I haven't been able to fit any in. As a hobby my knowlege of computers/programming is pretty decent but my transcript does not show it. So, I have really two questions. The first is: will colleges look at extracurricular computer science activities? And the second is: what kind of activity could I do? rml ================================================================================ Archive-Date: Mon, 18 Oct 1993 13:40:35 CST Sender: LP-Mgr@SHSU.edu From: dak@hathi.informatik.rwth-aachen.de (David Kastrup) Reply-To: LitProg@SHSU.edu, dak@HATHI.INFORMATIK.RWTH-AACHEN.DE Subject: Re: Lack of Literate Examples Date: 18 Oct 1993 17:58:33 GMT Message-ID: <29ulg9$1fv@urmel.informatik.rwth-aachen.de> MIME-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit To: LitProg@SHSU.EDU Lee Wittenberg writes: >> What I really want to say, is (just repeating others) that some standard for >> uploading should be defined, and I think this should require postscript source >> to be included in the upload. >I agree. I think that, at the very least, the original source (.w, >.web, .nw, etc.) and a PostScript version of the typeset output should >be provided. I think this would disenfranchise the least number of >people. I agree on both of these to be included, for they have a certain chance to allow a glance for those not yet into TeX and WEBs. The WEBs are, of course, important to show how it is done, and the ps for the results. It is a bad idea to require you download tools before glancing at them. However, where appropriate, I would opt for a formatting system dependent file as well which needs as few additions as possible. For troff, this would mean a source file with macro package *included* (if an own is required), for TeX a .dvi-file should be ok. Note that there are TeX systems around without Postscript support, and the same goes for troff. -- David Kastrup dak@pool.informatik.rwth-aachen.de Tel: +49-241-72419 Fax: +49-241-79502 Goethestr. 20, D-52064 Aachen ================================================================================ Archive-Date: Mon, 18 Oct 1993 13:40:54 CST Sender: LP-Mgr@SHSU.edu From: dak@hathi.informatik.rwth-aachen.de (David Kastrup) Reply-To: LitProg@SHSU.edu, dak@HATHI.INFORMATIK.RWTH-AACHEN.DE Subject: Lack of ftp-able LitTool Examples Date: 18 Oct 1993 17:51:05 GMT Message-ID: <29ul29$1be@urmel.informatik.rwth-aachen.de> MIME-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit To: LitProg@SHSU.EDU I have one problem: there are lots of tools around now, and lots of FAQs and so on. I would like to decode on one specific tool to choose for most tasks. There might be quite a point in having at least one language independent tool for Makefiles, weird scripts, shell programming, data arrangement, you name it. But I digress. Woukd it be possible that the fiercest advocates of any tool do not 1) proudly claim all their systems advantages, but 2) Make a presentation consisting of a) small examples displaying all important features, both as verbatim source text and tangled (or whatever) graphic result. b) compile this in a small .dvi file, and put it at ONE ftp-able place in one directory with *JUST* other representations in the same place. It would be prudent (possibly) to include a ps-version as well, since LitProgging might not always stay at TeX, and a WinWeb or so should have a way to make such a rep as well (and some might decide on their formatter only *after* they have seen how the tools which need it are). If Word cannot produce ps, w e l l... It would be even better to have one .dvi file with all that (or ps-file), but I doubt that the different macro packages needed would be *very* compatible. Besides, some work only with TeX, some with LaTeX, some with both... But let's leave the advocacies for later... Volunteers? This might help a lot... -- David Kastrup dak@pool.informatik.rwth-aachen.de Tel: +49-241-72419 Fax: +49-241-79502 Goethestr. 20, D-52064 Aachen ================================================================================ Archive-Date: Mon, 18 Oct 1993 17:26:01 CST Sender: LP-Mgr@SHSU.edu From: shf@netcom.com (Stuart Ferguson) Reply-To: LitProg@SHSU.edu, shf@NETCOM.COM Subject: Re: Levels of Abstraction Message-ID: Date: Mon, 18 Oct 1993 17:37:58 GMT To: LitProg@SHSU.EDU +-- C. M. Sperberg-McQueen writes: | Stuart Ferguson wrote: | > A good example of how literate programming tools break down is the | > example CWEB text that Knuth himself provides. In his toy example | > of a word count program, the code scraps often contain ordinary | > C-style comments. These comments (not even well typeset) indicate | > the need for a finer granularity of abstraction than that provided | > by the scrap mechanism. In-line comments allow descriptions of | > fragments of scraps that CWEB does not. | I am finding it hard to understand how your logic works here: as | a demonstration that literate programming tools cannot handle comments | on fine-grained details, you point out that Knuth's web for wc | contains (how odd) comments on fine-grained details. Since Cweb | allows inline comments, how is it possible for "In-line comments | [to] allow descriptions ... that CWEB does not"? It seemed like a step backwards to me to have a nicely typeset document describing a program and then have the code scraps contain untypeset comments in the code as if it were going to be read by a machine. Part of what I expect from a literate programming tool is the ability to write prose which describes each and every important detail of a program at the level at which it occurs. For some reason, Knuth chose to use inline comments to describe portions of his code instead of TeX, and I think he did this not because it was a good way to write commentary, but because the alternative was worse. He could have added another scrap for each item which he felt needed comment, but I would guess that Knuth thought that would break the code up too much. This suggests a problem to me -- that the scrap mechanism is not sufficient for properly explaining all the details in a C program. Saying that "Cweb allows inline comments" is not the same as saying that Cweb handles inline comments *well*. It's a small point, and it wasn't the main thrust of what I was trying to say, but it really did bother me. Those few C-style comments seemed to poison the whole idea of programs written for people and not compilers. -- Stuart Ferguson (shf@netcom.com) "Oh Dear Lord -- the canary exploded!" ================================================================================ Archive-Date: Mon, 18 Oct 1993 17:54:14 CST Sender: LP-Mgr@SHSU.edu From: bart@cs.tamu.edu (Bart Childs) Reply-To: LitProg@SHSU.edu, bart@CS.TAMU.EDU Subject: Inline comments and abstraction Date: 18 Oct 1993 22:01:18 GMT Message-ID: <29v3ne$8l0@TAMUTS.TAMU.EDU> Keywords: commenting formatting abstraction To: LitProg@SHSU.EDU It was written that the ordinary C-style comments were not even well typeset. I have no idea what was meant by that unless it was desired to have them not typeset at all. What was done is the comments are formatted like the documentation portions of sections. There are some places where this style of comment is a great help and far better than having an excess of trivial sections. A good example is section 11 of TeX.web. DEK declared a large number of constants and a comment on each. That comment often includes a wonderfully informative statement about relationships that must exist between other constants... These comments make extensive use of the same `escape to TeX mode' that also exists throughout his webs. Most will reference variables. This kind of precision is a great help. I remember being confused in my early reading about unix. The feature of being case sensitive is often mentioned and then when a command starts a sentence it is capitalized! I also note that he called these small parts sections or modules. (He used the words interchangeably.) I think that is a far better term than scraps because they were intentional, not leftovers as in most of the definitions of scrap. Bart Childs ================================================================================ Archive-Date: Mon, 18 Oct 1993 18:56:41 CST Sender: LP-Mgr@SHSU.edu From: vrkaramc@mtu.edu (Varada R. Karamchedu) Reply-To: LitProg@SHSU.edu, vrkaramc@MTU.EDU Subject: Chuck Moore etc etc THANKS !! Date: 18 Oct 1993 19:23:03 -0400 Message-ID: <29v8gn$979@maxwell1.ee> To: LitProg@SHSU.EDU To all who replied by email and posted on the net answering my query, thank you very much. Catch you later. -Raj ================================================================================ Archive-Date: Tue, 19 Oct 1993 07:30:26 CST Sender: LP-Mgr@SHSU.edu From: schrod@iti.informatik.th-darmstadt.de (Joachim Schrod) Reply-To: LitProg@SHSU.edu, schrod@ITI.INFORMATIK.TH-DARMSTADT.DE Subject: Re: Levels of Abstraction Date: 19 Oct 1993 11:42:11 GMT Message-ID: <2a0jqjINNl5d@rs18.hrz.th-darmstadt.de> To: LitProg@SHSU.EDU In article , shf@netcom.com (Stuart Ferguson) writes: > > It seemed like a step backwards to me to have a nicely typeset document > describing a program and then have the code scraps contain untypeset > comments in the code as if it were going to be read by a machine. [...] > For some reason, Knuth chose to use inline > comments to describe portions of his code instead of TeX, Sorry, but I don't understand you. The inline comments of CWEB are of course in TeX mode, and therefore you can make use of TeX markup there as well. If it's good style (and good looking ;-) to put a picture environment there might be questionable, but it's possible. I prefer to regard inline comments as the footnotes of program code: Used with care they can enhance the understanding of the document at large. Btw, that's no new feature. WEB did it already -- see my sig. So, would you please elaborate your critique that CWEB/WEB/FWEB inline comments are (a) not TeX material, and (b) useless? -- Joachim =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= Joachim Schrod Email: schrod@iti.informatik.th-darmstadt.de Computer Science Department Technical University of Darmstadt, Germany @d infinity=255 {$\infty$ (approximately)} [DEK, in weave.web] ================================================================================ Archive-Date: Tue, 19 Oct 1993 08:50:18 CST Sender: LP-Mgr@SHSU.edu From: schrod@iti.informatik.th-darmstadt.de (Joachim Schrod) Reply-To: LitProg@SHSU.edu, schrod@ITI.INFORMATIK.TH-DARMSTADT.DE Subject: Re: Inline comments and abstraction Date: 19 Oct 1993 12:12:24 GMT Message-ID: <2a0lj8INNl5d@rs18.hrz.th-darmstadt.de> Keywords: commenting formatting abstraction To: LitProg@SHSU.EDU In article <29v3ne$8l0@TAMUTS.TAMU.EDU>, bart@cs.tamu.edu (Bart Childs) writes: > > I also note that he called these small parts sections or modules. > (He used the words interchangeably.) I think that is a far better > term than scraps because they were intentional, not leftovers as > in most of the definitions of scrap. I prefer the simple term `program part'. For me, section is ok most of the time, but sometimes one must stress the difference between this `numbered entities' and their subparts. I _hate_ the term module. (In fact, Klaus and myself were one of the pushers to delete this word of CWEB.) A module is an entity with a distinct specification and implementation. One does not find this distinction in WEB. The concept of a module, first outlined by Parnas, later refined by Dennis, Ehrig & Mahr, and nowadays modernized by Booch, is a central one to all software engineering activities. It has _nothing_ to do with these WEB pieces. Please, don't throw away the CS terms we have worked so long for! For what it's worth, here is a definition of terms I use usually: Before we start with an overview of the implementation I want to explain the \cweb{} vocabulary I use while I guide you through this document. The commonly used terms sometimes denote two entities, but for the purpose of this style we need exact terms. I've tried to stick to a ``canonical'' computer science terminology. \begin{quotation} I distinguish two different structures in a \cweb{} file: The {\sl document structure\/} and the {\sl program structure}. A \cweb{} document consists of a series of {\sl sections}. Within this series some sections are especially emphasized, we call them the {\sl main sections}. (They are also called {\sl starred sections}, since their corresponding \cweb{} tag is~|@*|.) These main sections have a title, ordinary sections are untitled. A table of contents may therefore list only the main sections. Note that there is no hierarchy in the sections, they are all on the same level, ie, they are numbered subsequently. Each section consists of three parts: (1)~the {\sl documentation part}, (2)~the {\sl definition part}, and (3)~the {\sl program part}. Each of these parts can be empty. The documentation part is mostly text with \LaTeX{} tags. In this text material from {\sl restricted program mode\/} can appear. The definition part consists of a series of either {\sl macro\/} or {\sl format definitions}. The program part is one piece of a refinement, identified by a name (see below). A \cweb{} program consists of a tree of {\sl refinements}. A refinement is a list of program parts with the same name, ordered in appearence. The root of the tree is the refinement with the special name~|@c|. The program text is defined by the DFS (ie, infix-order) traversal of the tree. \end{quotation} \noindent The terminology outlined above is an overspecification for the \LaTeX{} style we're implementing here---nevertheless, the context of my explanation should be clear now.% (That's a verbatim copy from the cweb style.) Any critic? comments? -- Joachim =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= Joachim Schrod Email: schrod@iti.informatik.th-darmstadt.de Computer Science Department Technical University of Darmstadt, Germany ``Real programmers can write Fortran in any language.'' [... Well,] Real interface programmers can implement vi in any software envionment. [Hartson, Brandenburg, Hix] ================================================================================ Archive-Date: Tue, 19 Oct 1993 09:51:15 CST Sender: LP-Mgr@SHSU.edu From: bart@cs.tamu.edu (Bart Childs) Reply-To: LitProg@SHSU.edu, bart@CS.TAMU.EDU Subject: Sections modules chapters Date: 19 Oct 1993 13:58:55 GMT Message-ID: <2a0rqv$qt5@TAMUTS.TAMU.EDU> Keywords: sections modules chapters not-scraps To: LitProg@SHSU.EDU Thanks to Joachim for his posting that addressed an omission from my previous posting. He (and others) were eloquent some time ago about the use of the term module ... I had intended to reference that an point out that we adopted some of that for the latest rewrite on web-mode earlier in the year. We call the sections that begin with @* (in WEB, CWEB, and FWEB) by the name `chapter' and the others simply `section.' Thus we have keybindings like C-c gc `go to chapter' ,,, Bart Childs ================================================================================ Archive-Date: Tue, 19 Oct 1993 09:51:35 CST Sender: LP-Mgr@SHSU.edu From: marcus@x4u.desy.de (Marcus Speh) Reply-To: LitProg@SHSU.edu, marcus@X4U.DESY.DE Subject: Re: Revision Control Message-ID: Date: Tue, 19 Oct 1993 13:51:54 GMT To: LitProg@SHSU.EDU >>>>> On 18 Oct 1993 09:10:38 GMT, lynbech@daimi.aau.dk (Christian Lynbech) said: |> It wasn't exactly clear to me what RCS style Lee Wittenberg was referring to He was referring to the standard rcs.sty from the CTAN archives (e.g. pip.shsu.edu:/tex-archive/archive-tools/fileshdr/rcs.sty), by Nelson Beebe (acc. to private communication). I have had problems using the only keyword \RCSID{$Id$} in noweb pgms though. Will be happy to try this one now. -- ----------------------------------------------------------------------------- Marcus Speh, II.Inst.Theor.Physik,Luruper Chaussee 149, 22761 Hamburg,Germany Phone: +49-40 8998 2178, Fax: +49-40 8998 2267, Private: +49-40 801392 E-mail: , ================================================================================ Archive-Date: Tue, 19 Oct 1993 10:07:01 CST Sender: LP-Mgr@SHSU.edu From: marcus@x4u.desy.de (Marcus Speh) Reply-To: LitProg@SHSU.edu, marcus@X4U.DESY.DE Subject: Re: Lack of ftp-able LitTool Examples Message-ID: Date: Tue, 19 Oct 1993 14:32:25 GMT To: LitProg@SHSU.EDU [The following is copied from my World Wide Web Info pages on LitProg, sections "Tools" and "Examples". The appendix tells you what is where. To retrieve e.g. the PS version of the latest FWEB User's Manual, do FTP to ftp.desy.de [131.169.10.38] to directory pub/web/DOCUMENTS/ and get the file. _all_ files listed with "http" addresses are also retrievable via FTP on our server (this is not usually so on WWW). I include this as a reply to David Kastrup's request for LitProg samples and tool descriptions. -- Marcus Speh] =================================================== TOOLS Subject: Re: send http://info.desy.de/pub/www/projects/LitProg/Tools.html Date: Tue, 19 Oct 93 14:57:26 MET The requested document follows. Linked documents may be obtained using SEND
where the addresses are listed at the end. ________________________________________________________________________ List of Literate Programming Tools LIST OF LITERATE PROGRAMMING TOOLS Have a look at the LitProg Library[1] for a more complete overview and sources. CLiP (PostScript[2], plain[3]) A universal (language-independent) literate programming tool, currently ported to VAX/VMS and MS-DOS only. See also: CLiP Style[4] and Manual[5] (PostScript) CWEB[6] WEB System of Structured Documentation for C and C++. References [v3.0, all PostScript]: User's Manual[7], common[8], cweave[9], ctangle[10] FunnelWEB[11] Features and comparison with FWEB, by P. Lyon (original message to LitProg[12] mailing list). FWEB[13] WEB System of Structured Software Design and Documentation for Fortran-77, Fortran-90, Ratfor, C, C++ and TeX. References [v1.30, all PostScript]: fwebmac[14] [40p.], User's Manual [body[15], index[16], 200 p.], guide[17] [20p.]. Here is John Krommes' hypertextified FWEB Info[18] Glasgow LitProg Tools A GNU Texinfo-based suite of literate programming tools from Glasgow, at ftp.dcs.glasgow.ac.uk:/pub/haskell/glasgow/. Here is the documentation[19] [PostScript[20]]. NOWEB (plain[21], PostScript[22]) "Literate-Programming Tools Need Not Be Complex", by N. Ramsey. NUWEB[23] (PostScript) Yet another simple Literate Programming tool for arbitrary programming languages, with LaTeX as formatter. Command Summary[24] (ps) WinWordWEB[25] A WORDWEB (HyperText literate programming[26]) Last updated September 22, 1993 References from this document:- [1] gopher://Niord.shsu.edu:70/11gopher_root%3a%5b_DATA.LITPROG%5d [2] http://info.desy.de:80/pub/faq/web/clip/clip_ann.ps [3] http://info.desy.de:80/gnu/ftp/pub/faq/web/clip/clip_ann.plain [4] http://info.desy.de:80/pub/faq/web/clip/clip_ann.ps [5] file://sun01.info.wau.nl/clip/ms_dos/clip_man.ps [6] http://heplibw3.slac.stanford.edu:80/FIND/FREEHEP/NAME/CWEB/FULL [7] http://info.desy.de:80/pub/web/DOCUMENTS/cweb/cwebman.ps [8] http://info.desy.de:80/pub/web/DOCUMENTS/cweb/common.ps [9] http://info.desy.de:80/pub/web/DOCUMENTS/cweave.ps [10] http://info.desy.de:80/pub/web/DOCUMENTS/cweb/ctangle.ps [11] http://info.desy.de:80/pub/faq/web/funnelWEB/funnelWEB.html [12] http://info.desy.de/pub/www/projects/LitProg/Mailing.html [13] http://heplibw3.slac.stanford.edu:80/FIND/FREEHEP/NAME/FWEB/FULL [14] http://info.desy.de:80/pub/web/DOCUMENTS/fweb-manual/macros.ps [15] http://info.desy.de:80/pub/web/DOCUMENTS/fweb-manual/manual.ps [16] http://info.desy.de:80/pub/web/DOCUMENTS/fweb-manual/index.ps [17] http://info.desy.de:80/pub/web/DOCUMENTS/fweb-manual/guide.ps [18] http://info.desy.de/pub/www/projects/LitProg/info/top.html [19] http://info.desy.de/pub/www/projects/LitProg/glasgow/top.html [20] http://info.desy.de:80/gnu/doc/litprog/lit2x-0.16-literate.ps [21] http://info.desy.de:80/gnu/ftp/pub/faq/web/noweb/noweb.html [22] http://info.desy.de:80/pub/faq/web/noweb/noweb.ps [23] http://info.desy.de:80/pub/web/nuweb/nuweb.ps [24] file://ftp.shsu.edu/tex-archive/web/nuweb/nuweb-summary.ps [25] gopher://Niord.shsu.edu:70/11gopher_root%3a%5b_DATA.FILESERV.WORDWEB%5d [26] http://info.desy.de/pub/www/projects/LitProg/HTML.html =================================================== SAMPLES Subject: Re: send http://info.desy.de/pub/www/projects/LitProg/Samples.html Date: Tue, 19 Oct 93 15:01:48 MET The requested document follows. Linked documents may be obtained using SEND
where the addresses are listed at the end. ________________________________________________________________________ Archives and Examples Overview ARCHIVES AND SELECTED EXAMPLES Literate Programming Archives Various stuff, including WEB systems for Maple, Reduce, Ada and APL, CNOWEB, DOSNOWEB, FunnelWEB, MWEB, PC-WEB, SpiderWEB,... can be found at the following archives in the US and in Europe: George D. Greenwade's archive at Niord.shsu.edu[1] (gopher server) the repository at ftp.uni-stuttgart.de in directory pub/soft/tex/web[2] the UK TeX Archive at ftp.tex.ac.uk[3] Joachim Schrod's archive at ftp.th-darmstadt.de[4]. Selected Samples Sample programs for FWEB are contained in the FWEB distribution at lyman.pppl.gov[5]. Here, you can look at woven sample output (PostScript[6], ASCII[7]). A couple of sample files for CWEB can be retrieved from the freeHEP[8] server (in directory pub/freehep/languages/cweb[9]) as well. Here, you can look at woven sample output (PostScript[10], ASCII[11]). More sample programs for CWEB are contained in the CWEB distribution at labrea.stanford.edu in directory pub/cweb/examples[12]. The simple desk calculator program from the Kernighan & Ritchie standard text on C was transformed into a instructive LitProg example for multiple source files by Cameron Smith. It can be retrieved via anonymous FTP from ftp.desy.de[13] in directory pub/web/cweb/kr-cweb-sample. Here, you can look at its woven output (PostScript[14], ASCII[15]). Last updated June 20, 1993 References from this document:- [1] gopher://Niord.shsu.edu:70/11gopher_root%3a%5b_DATA.LITPROG%5d [2] file://ftp.uni-stuttgart.de/pub/soft/tex/web [3] gopher://ftp.tex.ac.uk:70/11/archive/Archive%20directory/web [4] file://ftp.th-darmstadt.de/pub/programming/literate-programming [5] file://lyman.pppl.gov/pub/fweb/v1.30/demos [6] http://info.desy.de:80/pub/web/fweb/IntArray.ps [7] http://info.desy.de:80/pub/web/fweb/IntArray.html [8] http://heplibw3.slac.stanford.edu:80/FIND/FHMAIN.HTML [9] file://freehep.scri.fsu.edu/freehep/languages/cweb [10] http://info.desy.de:80/pub/web/cweb/String-sample/String2.ps [11] http://info.desy.de:80/pub/web/cweb/String-sample/String2.html [12] file://labrea.stanford.edu/pub/cweb/examples [13] http://info.desy.de:80/pub/web/cweb/kr-cweb-sample [14] http://info.desy.de:80/pub/web/cweb/kr-cweb-sample/calc.ps [15] http://info.desy.de:80/gnu/ftp/pub/web/cweb/kr-cweb-sample/calc.html -- ----------------------------------------------------------------------------- Marcus Speh, II.Inst.Theor.Physik,Luruper Chaussee 149, 22761 Hamburg,Germany Phone: +49-40 8998 2178, Fax: +49-40 8998 2267, Private: +49-40 801392 E-mail: , ================================================================================ Archive-Date: Tue, 19 Oct 1993 10:15:51 CST Sender: LP-Mgr@SHSU.edu Date: Tue, 19 Oct 93 10:10:47 CDT From: preston@cs.rice.edu (Preston Briggs) Reply-To: LitProg@SHSU.edu, preston@CS.RICE.EDU Message-ID: <9310191510.AA26110@dawn.cs.rice.edu> To: LitProg@shsu.edu Subject: scraps, modules, sections I agree with Joachim Schrod about "module" already being heavily overloaded in computer science. Unfortunately, I also feel that "section" has an adequate meaning, at least in the context of Latex. Therefore, I've tried to use "scrap" where possible. Of course, people will be able to find errors in my usage, but "scrap" is goal, even if I fall down occasionally in practice. Yes, "scrap" has a perhaps unfortunate implication of leftover or remnant that might put off some people. However, it has the big advantage of not having any more precise CS meaning. Preston Briggs ================================================================================ Archive-Date: Tue, 19 Oct 1993 10:21:52 CST Sender: LP-Mgr@SHSU.edu From: marcus@x4u.desy.de (Marcus Speh) Reply-To: LitProg@SHSU.edu, marcus@X4U.DESY.DE Subject: Re: Usage of RCS in *WEB Documents (was Re: Some thoughts) Message-ID: Date: Tue, 19 Oct 1993 14:09:13 GMT To: LitProg@SHSU.EDU >>>>> On 18 Oct 1993 11:22:23 GMT, schrod@iti.informatik.th-darmstadt.de (Joachim Schrod) said: [...comments on RCS & WEB and a new RCS style by Schrod...] |> Why didn't we distribute it yet? |> -- We need a smoother integration into CVS, we're not interested in |> RCS per se. |> But if there is enough interest, I can make a pre-release ready. I am also not particularly interested in having such a style for RCS alone. I am trying to drag a local collaboration into the use of both CVS [easy, with Per Cederquist's nice Texinfo tutorial existing now] and a language independent LitProg tool [well, you may guess how hard *that* is -- will see what happens if they notice that all their user documentation has become "literate" over night.. :-) ]. I would be very interested in obtaining even a prerelease. ----------------- [Some Literati not in CS may wonder (as I would have 1 year ago): CVS ("concurrent versions system") is a front end to RCS ("revision control system") which extends the notion of revision control from a collection of files in a single directory to a hierarchical collection of directories consisting of revision controlled files. These directories and files can be combined together to form a software release. Both obtainable from prep.ai.mit.edu in pub/gnu. Per's tutorial (release 0.7) is in ftp.desy.de:/pub/gnu/cvs/cvs-tutorial.ps. Not everyone -even in CS- may know that there is a version to work with CVS in a group of developers at *remote* sites, developed at SLAC and mainly in use in the High Energy Physics community. rCVS patches: ftp.slac.stanford.edu:/pub/sources/rcvs-0.6.4.tar.Z] -- ----------------------------------------------------------------------------- Marcus Speh, II.Inst.Theor.Physik,Luruper Chaussee 149, 22761 Hamburg,Germany Phone: +49-40 8998 2178, Fax: +49-40 8998 2267, Private: +49-40 801392 E-mail: , ================================================================================ Archive-Date: Tue, 19 Oct 1993 10:22:01 CST Sender: LP-Mgr@SHSU.edu From: marcus@x4u.desy.de (Marcus Speh) Reply-To: LitProg@SHSU.edu, marcus@X4U.DESY.DE Subject: Re: compu transcript Message-ID: Date: Tue, 19 Oct 1993 14:21:03 GMT To: LitProg@SHSU.EDU >>>>> On 18 Oct 1993 12:41:10 -0500, rml@genesis.MCS.COM (Ryan Lee) said: Ryan> Could someone tell me what sorts of programming contests/ Ryan> activities/etc. I could put on my transcript for college? Although Ryan> I don't plan to major in computer sciences, I am a computer enthusiast Ryan> who programs intermediately with C and will likely remain involved with Ryan> computers. But unfortunately my high-school offers very few computer Ryan> science courses and I haven't been able to fit any in. As a hobby my Ryan> knowlege of computers/programming is pretty decent but my transcript Ryan> does not show it. Ryan> So, I have really two questions. The first is: will colleges look Ryan> at extracurricular computer science activities? And the second is: Ryan> what kind of activity could I do? If you can wait for the Spring 94 semester, GNA (Global Network Academy) will offer programming courses on the Internet on college level. A course program will be out by January 94. The first semester will include topics like C, parallel and literate programming, astrophysics, computer & writing ...etc. For further information please refer to one or all of Usenet group -> alt.uu.future World Wide Web -> http://sturgeon.mit.edu:8001/ MediaMOO -> telnet microworld.mit.edu 8888 -- ----------------------------------------------------------------------------- Marcus Speh, II.Inst.Theor.Physik,Luruper Chaussee 149, 22761 Hamburg,Germany Phone: +49-40 8998 2178, Fax: +49-40 8998 2267, Private: +49-40 801392 E-mail: , ================================================================================ Archive-Date: Tue, 19 Oct 1993 10:47:36 CST Sender: LP-Mgr@SHSU.edu From: marcus@x4u.desy.de (Marcus Speh) Reply-To: LitProg@SHSU.edu, marcus@X4U.DESY.DE Subject: LitProg on the World Wide Web [regular posting] Message-ID: Date: Tue, 19 Oct 1993 14:44:20 GMT To: LitProg@SHSU.EDU ----------------------------------------------------------------------------- * Literate Programming on the World Wide Web ----------------------------------------------------------------------------- FYI, there is a wealth of information on Literate Programming, the art of structured programming and documentation [especially using WEB-like systems with TeX formatting] available on the World Wide Web [WWW], a distributed HyperText system, a network of documents connected by links which can be activated electronically. Examples for LitProg environments are WEB for Pascal (DEK), CWEB for C/C++ (Levy/Knuth), FWEB for C/C++/Fortran/ratfor/TeX (Krommes)...and many more. ----------------------------------------------------------------------------- * How to get to the Web ----------------------------------------------------------------------------- If you have a WWW browser up and running, try going to http://info.desy.de/ (this brings you to the DESY home page), and look for "User Documents" in the panel which appears. The precise URL is http://info.desy.de/pub/www/projects/LitProg.html If you have no clue what WWW is, you can go over the Internet with telnet info.cern.ch which brings you to the WWW Home Page at CERN. You are now using the simple line mode browser. To move around the Web, enter the numbers given after an item. To go to the Literate Programming documents, enter go http://info.desy.de/pub/www/projects/LitProg.html This is what you should see now: ----------------------------------------------------------------------------- * What you will see here ----------------------------------------------------------------------------- Getting Started[2] A first look into Literate Programming with WEB Editing[3] GNU Emacs mode for WEB programming Tools[4] Common, freely available Literate Programming environments Examples[5] Literate Programming archives and selected examples LitProg Library[6] George D. Greenwade's Literate Programming Library at Niord.shsu.edu. Experimental service: Archive Search[7] LITPROG Discussion List[8] Information on the Literate Programming Mailing List. Now, there is also a newsgroup, comp.programming.literate[9] FAQs[10] Lists of Frequently Asked Questions for WEB systems Further Reading Nelson Beebe's Literate Programming bibliography at ftp.math.utah.edu in directory /pub/tex/bib[11] (files litprog.*) HyperLitProg[12] Literate Programming using HyperText[13] Techniques OO-LitProg[14] Thoughts on Object-Oriented[15] Literate Programming [[Now you can continue climbing down the documentation tree by entering numbers 1-14 and follow your own interests]] ----------------------------------------------------------------------------- * More on Browsing the Web ----------------------------------------------------------------------------- The by far nicest way of "browsing" through WWW uses the X-Terminal based tool "NCSA Mosaic". Binaries for many platforms (ready for use) and sources are available via anonymous FTP from ftp.ncsa.uiuc.edu in directory Web/xmosaic. The general FTP repository for browser software is info.cern.ch (including a hypertext browser/editor for NeXTStep 3.0) If you cannot go through TELNET, you can still retrieve WWW documents by e-mail: send a mail to listserv@info.cern.ch with a line in it saying just HELP to get back detailed instructions. Your mail system must have a mail gateway to the internet mail. ----------------------------------------------------------------------------- * Contact for Further Information ----------------------------------------------------------------------------- Please feel free to contact me for questions, suggestions and further contributions, or just to tell me whether you found this information useful in any way. For questions related to WWW, consult the WWW-FAQ: available via anonymous FTP from rtfm.mit.edu in directory pub/usenet/news.answers/www/faq, or on WWW at URL http://www.vuw.ac.nz:80/who/Nathan.Torkington/ideas/www-faq.html Enjoy. Oct 19-93 -- ----------------------------------------------------------------------------- Marcus Speh, II.Inst.Theor.Physik,Luruper Chaussee 149, 22761 Hamburg,Germany Phone: +49-40 8998 2178, Fax: +49-40 8998 2267, Private: +49-40 801392 E-mail: , ================================================================================ Archive-Date: Tue, 19 Oct 1993 11:43:45 CST Sender: LP-Mgr@SHSU.edu Date: Tue, 19 Oct 93 17:37:12 +0100 From: coates@spectro.jussieu.fr Reply-To: LitProg@SHSU.edu, coates@SPECTRO.JUSSIEU.FR Message-ID: <9310191637.AA02790@lutidine.spectro.jussieu.fr> To: LitProg@shsu.edu Subject: (My) long postings Dear Readers, I wrote that maybe my postings were too long. I had two or three personal replies saying they were, and complaining about my long .sig (it is true that my laboratory has a long address, plus I have a bilingual disclaimer). I'll leave out the .sig this time. There was a comment that my postings might be more interesting to read if I included less of what the previous poster said. I'm not sure whether I am interested in creating postings that are quicker and more interesting to read, but unreasonably biased by my own interpretation of what was said before. I'll have to decide that. Otherwise, let me quickly note that I will sign off from LitProg at the end of this week, when I return to Australia, but will be back again at the end of November, from Brisbane, Australia. Cheers, Tony. ================================================================================ Archive-Date: Tue, 19 Oct 1993 11:52:30 CST Sender: LP-Mgr@SHSU.edu From: ucacgcj@ucl.ac.uk (Gordon C Joly) Reply-To: LitProg@SHSU.edu, ucacgcj@UCL.AC.UK Subject: SOLVE tags and Meta Tags (was Re: Some thoughts) Message-ID: <1993Oct19.154205.60954@ucl.ac.uk> Date: Tue, 19 Oct 1993 15:42:05 GMT To: LitProg@SHSU.EDU In article Lee Wittenberg writes: >Shaker writes: > >> I program in Perl. Our source files are under RCS. Each time, a source >> file is checked back in, people put a line or two of comments. These >> comments are almost always of short term value, if any. In other >> words, if different programmers work on a source file within the same >> week (or month) say, these comments help to identify who changed what, >> when. As long term documentation, these are useless. >>[...] >I don't know of any general feature that will help you, but Tipton >Cole+Co. (where I worked last year) dealt with the same problem in the >following way (code is written using noweb & LaTeX): > > [...] > > As the the $LOG$ stuff (which your question was about), we never > came up with a really good solution. "\RCSdef{$LOG$}" (I forget the > exact syntax) didn't really work well (at least we couldn't tame > it), so we just leave the $LOG$ at the end of the .nw file where > programmers can get to it if they want, but it doesn't get into > the woven output. > >Hope this helps. > > -- Lee > leew@pilot.njin.net I wanted to do this type of thing with a code browser. My solution is to invent a language "on the fly" and then use a standard browser like UNIX ctags or extensions. Here is a short abstract (RN/92/78 at UCL.CS). Comments by email welcome. ------------------------------- Dynamically defined tags for annotation at the description level. G. C. Joly Department of Computer Science, University College London, Gower Street, LONDON WC1E 6BT, U.K. Email: G.Joly@cs.ucl.ac.uk ABSTRACT This paper shows how the user can manipulate the process of searching for known (method) func- tions and at the same time provide their own tag- ging mechanism through a single interface. 1. Introduction. One of the fundamental concepts that is debated in the field of Object Oriented programming (and now OO design) is that of reuse. The Cognitive Browser (CogBrow) project [1] has been developing a set of browsing tools that extend a class browser, such as the Smalltalk Class Browser, to aid the programmer in their search for objects to reuse. Exper- imental work has shown that the user changes their view of the code very rapidly, that is to say from one day to the next. The use of tags, applied to spreadsheet designs, is reported in [2], and this paper reports a direct application to OO systems. Programmers and designers will often sketch a flow chart then turn to writing pseudo-code, and CogBrow will support this flexibility as much as possible. If the Cognitive Browser is left standing idle and the user turns to pencil and paper then the Browser is of little value. A prototype system has been built using the EMACS edi- tor and a short PERL script; we call this system "stags" (for "super-tags" or "SOLVE tags": for further information on the SOLVE language, see for example [1]). 2. Arbitrary placing of tags and browsing using EMACS. Stallman [3] developed the EMACS "editor" for extensi- bility. The EMACS Lisp language in which EMACS is now mostly written can be used to modify the behaviour of the "editor" in different "modes". New "modes" are created, which be - 2 - viewed in text windows, either by the user or as library packages. Currently EMACS can act (among other things) as a folding editor, an interface to a mail system and a source level debugger. Each mode is dynamically self documenting. Source code, in multiple files which may be spread across many directories, can be browsed using the EMACS tags facility "etags". In a sense, "etags" allows the dynamic generation of an index over all the code. Since tags are language dependent, (the context of) the mode (corresponding to a distinct "language"), is used to create and scan the tags tables. For example, in C any function, in FORTRAN any function or subroutine and in (EMACS) Lisp, any function defined with defun and any variable defined with defvar or defconst (see Schoonover et al [4]). Further extensions to "etags" (EMACS tags) have been added to the TeX and LaTeX document preparation languages, where commands `chapter', `section', `subsection', `subsub- section', `eqno', `label', `ref', `cite', `bibitem' and `typeout' are all tags. In this case, instances of (equa- tion) labels and chapter (headings) will both be found (if the text strings correspond); in fact the user may have this notion in mind. The extension of "etags" (for the C language) to C++ was carried out by Yacko [5]. Here, the system could search for classes and includes the notion of a class hierarchy, which is displayed in a textual form, using indentation to denote subclassing. Note that a similar program in EMACS Lisp is currently maintained by Sam Kendall (email kendall@centerline.com), which allows the user to search for classes using command line completion. 3. An extension of EMACS style tags for browsing Payne and Green [6] describe a TAG (task-action gram- mar) as "a formal device... a description of a task as a set of semantic components". In contrast, the system of "stags" proposed in this paper takes the view that user is fully aware of the semantics and it is the system which provides the mechanical browsing (on text files). Therefore "stags" are completely free, without any notion of formal grammar or structure. A small script by David Megginson (email dmeg- gins@acadvm1.uottawa.ca) called PETAGS and written in the Perl language, as described in [7] allowed the extension of tags to an arbitrary computer language, which Pascal, COBOL or BASIC. From this starting point, it is possible to extend the idea further. We consider three modifications: super- sets of languages, sub-sets of languages, and the "descrip- tion level", that is "arbitrary attributes and relation- ships... in a browsable form", see [1] - 3 - In the first case, a user could take the standard set of tag words by the tags program (described above) and add further tag words. One example of this sort of procedure is where some PostScript (tm) interpreters will process code inside a comment. The second category allows faster browsing of a subset of the language. Consider the standard etags definitions of EMACS Lisp. It would be possible to interactively restrict tagging to ``defun'' and not to ``defvar'' and ``defconst''. The final case could be any hybrid, "stags", in which the user chooses dynamically over the (fixed) source files. It would be possible to tag comments dynamically to existing code so that the user could browse comments only, if they wished. Note that the users themselves may or may not have added the comments to the code. If they for example added their own initials when making changes, then these could be tagged. In this case, since the "stags" are processed simply (by a search operation), the user would have to produce a meaningful set of tag words. If the user chose to find all entries with their own initials in a comment field, they should be able to search for any words after the tag word up to the "end of comment". For example, if comments begin with ``//'', then the following lines // xxyz changed size of windows // and filled in background would allow a search for all occurrences of ``changed'' or ``window'', for user (that is to say tag word) ``xxyz''. Note that the support for tags searches in EMACS allows this operation to be carried out over more than one (UNIX (tm)) directory. 4. Conclusions The proposal is to perform some experiments with this system of "stags" with a small set of users, to see if this arbitrary scanning of code is fruitful for code reuse. The base language of choice for would be a fully Object Oriented language, such as SOLVE, but C++ or another language could be considered, or even software written in several lan- guages. The current browsing method is through the EMACS editor, but an extension to form part of the graphical user interface of the Cognitive Browser is planned. The proposed system is far from complete in any sense, but may provide a new dimension for browsing source code. References 1. Green, T. R. G., Gilmore, D. J., Blumenthal, B, Davies, S., and Winder, R., "Towards a cognitive browser for - 4 - OOPS," International Journal on Human-Computer Interac- tion, vol. 4, no. 1, pp. 1-34, 1991. 2. Hendry, D., Green, T. R. G., Gilmore, D., and Davies, S., "Improving the communicability of speadsheet designs: Annotating with descriptive tags," in Psychol- ogy in Programming Interest Group - 5th Workshop, Paris, (unpublished), 1992. 3. Stallman, R. M., "EMACS: The Extensible, Customizable, Self-Documenting Display Editor," in Interactive Pro- gramming Environments, ed. David R. Barstow, Howard E. Shrobe and Erik Sandwell., McGraw-Hill, New York, 1986. 4. Schoonover, Micheal A., Bowie, John S., and Arnold, William R., GNU Emacs: Unix Text Editing and Program- ming, Addison Wesley, Reading, Mass, 1992. 5. Yacko, Nancy Jane, "A GNU Emacs Browser for C++ Code Development," M.Sc. Thesis, University of Illinois at Urbana-Champaign, Urbana, Illinois, 1987. 6. Payne, Stephen J. and Green, T. R. G., "Task-Action Grammar: the model and its developments," in Task anal- ysis for human-computer interaction, ed. D. Diaper, pp. 75-107, Ellis Horwood Publishers, Chichester, 1989. 7. Wall, Larry and Schwartz, Randall L., Programming perl, O'Rielly & Associates Inc., Sebastopol, CA, 1990. ------------------------------- -- Gordon Joly Phone +44 71 380 7777 ext 3703 FAX +44 71 387 1397 Internet: G.Joly@cs.ucl.ac.uk ucacgcj@ucl.ac.uk Computer Science, University College London, Gower Street, LONDON WC1E 6BT ================================================================================ Archive-Date: Tue, 19 Oct 1993 14:48:13 CST Sender: LP-Mgr@SHSU.edu Date: Tue, 19 Oct 93 15:42:35 EDT From: Lee Wittenberg Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET To: LitProg@shsu.edu, lynbech@daimi.aau.dk Subject: Re: Revision Control Message-ID: A number of people have remarked on the rcs.sty file I mentioned in one of my messages. Until now, I didn't know there was more than one. The one I was referring to is by Tom Verhoeff, and boils down to the following 2 definitions: \def\RCSdef $#1${\typeout{RCS keyword string: $#1$}\RCS@def#1: {} :.} \def\RCS@def#1: #2 :#3.{\expandafter\def\csname RCS#1\endcsname{#2}} I apologize for any confusion. Mea culpa. -- Lee leew@pilot.njin.net ================================================================================ Archive-Date: Tue, 19 Oct 1993 15:09:37 CST Sender: LP-Mgr@SHSU.edu Date: Tue, 19 Oct 93 16:06:20 EDT From: Lee Wittenberg Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET To: LitProg@shsu.edu Subject: Literate Programming Examples Message-ID: As David Kastrup has resuscitated the issue of LP examples, I no longer have to apologize for my delay in making such examples available. I have put a couple of literate programs of mine in the ~/pub/leew/samples.LP directory of bart.kean.edu, where anonymous ftp'ers can grab them if they so desire. I would prefer not to use bart for this, but until there is a central repository for LP examples, it will have to do. Both programs are written in CWEB, and are provided in .w, .dvi, and .ps format (CWEB, TeX output, and PostScript, for the uninitiated). When I can, I will add a few noweb programs (for various reasons I can't do it now). I also plan to put all non-proprietary programs I write from now on (excepting trivial stuff) in this directory (or a central repository, if one is available. I hope other LP'ers will do likewise. The 2 programs are called ``Puzzle'' and ``EventLib.'' The former is a simple little program I wrote to try to solve a brainteaser presented by a student. The student was neither a CS major nor interested in programming, so I wrote the program with the idea of his being able to read it. It should be a nice example for beginners. EventLib is a prototype library of routines for event-driven programming that avoids the agony of event loops (``EventLib'' stands for both ``event library'' and ``event liberation''). It began life as a non-literate program, was translated to Spidery C (my first major LP project), and from thence to CWEB 3.0 (as CWEB now supports Standard C). Because of its many lives, it's a bit of a mixed bag, and does not use any LP techniques I have since discovered. It also has a semi-major (known) bug. However, it's an interesting idea, and a reasonably good literate program, and I can't think of any reason not to let people see it. It is also a ``work in progress,'' so any comments or criticisms you might care to make will be cheerfully incorporated into future versions (assuming I find the time -- or funding -- to get back to the project). More information is contained in the README file. I'm looking forward to your critical comments (he said, putting on a brave face :-). -- Lee leew@pilot.njin.net ================================================================================ Archive-Date: Tue, 19 Oct 1993 15:19:01 CST Sender: LP-Mgr@SHSU.edu Date: Tue, 19 Oct 93 16:12:24 EDT From: Lee Wittenberg Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET To: LitProg@shsu.edu Subject: CWEB comments Message-ID: I'm a bit confused. A number of people have made the claim that CWEB does not typeset comments. As far as I know, CWEB typesets comments exactly as it does the text sections: in roman type, with TeX codes completely usable. The cwebmac.tex macros also include options to typeset comments in sans serif and to use special symbols as comment markers. Am I missing something here? -- Lee leew@pilot.njin.net ================================================================================ Archive-Date: Tue, 19 Oct 1993 15:27:10 CST Sender: LP-Mgr@SHSU.edu Date: Tue, 19 Oct 93 16:23:20 EDT From: Lee Wittenberg Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET To: LitProg@shsu.edu, schrod@iti.informatik.th-darmstadt.de Subject: Re: Inline comments and abstraction Message-ID: Joachim Schrod mentioned the terribleness (is that a word?) of the term ``module'' as used in the original WEB literature. I agree with him as to the superiority of ``section'' in this regard. So does DEK, apparently, as this terminology has been adopted in the most recent versions of CWEB. However, my hands down favorite in the terminology game is Norman Ramsey's use of ``chunks'' in noweb. The word chunk carries no ``excess baggage,'' as to both module and section (the former in programming, the latter in word processing). It's unambiguous to speak of ``code chunks'' and ``text chunks'' and the terms are readily understandable. Chunk also has the advantage that it's only one syllable, and therefore, easier to say. I don't mean to force anyone to adopt a new terminology, or to start any new religious wars. I just wanted to make the ``chunk'' terminology a bit more widely known. -- Lee leew@pilot.njin.net ================================================================================ Archive-Date: Tue, 19 Oct 1993 16:19:49 CST Sender: LP-Mgr@SHSU.edu Date: Tue, 19 Oct 93 16:06:13 CDT From: preston@cs.rice.edu (Preston Briggs) Reply-To: LitProg@SHSU.edu, preston@CS.RICE.EDU Message-ID: <9310192106.AA03835@dawn.cs.rice.edu> To: LitProg@shsu.edu Subject: Literate Programming Examples Our group at Rice is writing an experimental optimizer, mostly in C, using nuweb. I've put several examples arising from our efforts out for anonymous ftp, from cs.rice.edu, in the directory public/preston They're all in postscript form. They're also fairly heavy reading if you're not familiar with the literature. We haven't settled into a particular style of literate programming, so they tend to vary in form, depending on the author's (evolving) preferences. 3 of the programs are optimizations. 1 is an experimental implementation of a particular algorithm to be incorporated into another optimization. 1 is a testing facility (generates make files, among other things) 1 is in progress, and will describe the entire project. Currently, it describes the intermediate language and the interface to a large body of shared utilities. Each program was written by a different person, so there's some variety in the approaches to the problems. However, they were all viciously criticised in walkthroughs, so you'll also see some common ideas. Nota bene -- Printing all these files will require about 300 pages of paper. I'd preview them first, and print only what looks interesting or representative. Preston Briggs ================================================================================ Archive-Date: Tue, 19 Oct 1993 17:39:09 CST Sender: LP-Mgr@SHSU.edu From: schrod@iti.informatik.th-darmstadt.de (Joachim Schrod) Reply-To: LitProg@SHSU.edu, schrod@ITI.INFORMATIK.TH-DARMSTADT.DE Subject: WEB mode (was Re: Sections modules chapters) Date: 19 Oct 1993 21:39:17 GMT Message-ID: <2a1mq5INNhd4@rs18.hrz.th-darmstadt.de> Keywords: sections modules chapters not-scraps To: LitProg@SHSU.EDU In article <2a0rqv$qt5@TAMUTS.TAMU.EDU>, bart@cs.tamu.edu (Bart Childs) writes: > > Thus we have keybindings like C-c gc `go to chapter' ,,, Btw, that was a gripe I have always with the WEB mode (besides that it doesn't support AUC-TeX and c++-mode): It binds `C-c LETTER'. From the elisp manual: * Please do not define `C-c LETTER' as a key in your major modes. These sequences are reserved for users; they are the *only* sequences reserved for users, so we cannot do without them. Instead, define sequences consisting of `C-c' followed by a non-letter. These sequences are reserved for major modes. Changing all the major modes in Emacs 18 so they would follow this convention was a lot of work. Abandoning this convention would waste that work and inconvenience the users. This $@#!!@# mode redefines all my user-specific definitions... (Of course, it isn't the only one. bibtex-mode and html-mode do the same. :-( ) And if you might add a web-mode-load-hook, that would be great, too. -- Joachim =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= Joachim Schrod Email: schrod@iti.informatik.th-darmstadt.de Computer Science Department Technical University of Darmstadt, Germany ================================================================================ Archive-Date: Tue, 19 Oct 1993 17:39:15 CST Sender: LP-Mgr@SHSU.edu From: schrod@iti.informatik.th-darmstadt.de (Joachim Schrod) Reply-To: LitProg@SHSU.edu, schrod@ITI.INFORMATIK.TH-DARMSTADT.DE Subject: Re: Revision Control Date: 19 Oct 1993 21:33:36 GMT Message-ID: <2a1mfgINNhd4@rs18.hrz.th-darmstadt.de> To: LitProg@SHSU.EDU In article , marcus@x4u.desy.de (Marcus Speh) writes: > >>>>> On 18 Oct 1993 09:10:38 GMT, lynbech@daimi.aau.dk (Christian Lynbech) said: > > |> It wasn't exactly clear to me what RCS style Lee Wittenberg was referring to > > He was referring to the standard rcs.sty from the CTAN archives > by Nelson Beebe Thank you for this hint to yet another rcs style. Perhaps I should add that this style is by no means standard. In fact, it's the third rcs.sty, I'm aware of: One by Piet v.Oostrum, this one, and one by myself (you see, I'm biased. :-). Piet's is the one which is the best known, it's the one which may be found in the latex/contrib/misc directory of the CTAN. (My style option will be available from latex/contrib/rcs after one of the CTAN managers has answered my question posed a month ago. Hint, hint... ;-) Currently, you can fetch it from ftp.th-darmstadt.de:pub/tex/latex/. I had a look at Nelson's style just a few minutes ago. Luckily it doesn't conflict with one of the others. I will add support for the tags defined there to my rcs style. Dave Love already pointed out another shortcoming (usage with co -kv) which will be addressed, too. -- Joachim =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= Joachim Schrod Email: schrod@iti.informatik.th-darmstadt.de Computer Science Department Technical University of Darmstadt, Germany ================================================================================ Archive-Date: Tue, 19 Oct 1993 17:54:48 CST Sender: LP-Mgr@SHSU.edu Message-ID: <9310192249.AA23077@mailee.bellcore.com> To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET Subject: Re: Literate Programming Examples Date: Tue, 19 Oct 93 18:49:07 -0400 From: norman@bellcore.com Reply-To: LitProg@SHSU.edu, norman@BELLCORE.COM I think it's high time we had a central repository of literate-programming examples. I think CTAN is the natural place for it, but if CTAN isn't interested, I'll ask my management if we can arrange something here. (The problem is that our lawyers won't let us make an ftp area that is both readable and writable, and it takes real staff hours to move things from an incoming to a readable directory.) Norman ================================================================================ Archive-Date: Tue, 19 Oct 1993 18:16:02 CST Sender: LP-Mgr@SHSU.edu From: mbrown@athos.cs.ua.edu (Marcus Brown) Reply-To: LitProg@SHSU.edu, mbrown@ATHOS.CS.UA.EDU Message-ID: <9310192312.AA22346@athos.cs.ua.edu> Subject: Re: Inline comments and abstraction To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET Date: Tue, 19 Oct 1993 18:12:15 -0500 (CDT) Content-Type: text Lee Wittenberg wrote: > > However, my hands down favorite in the terminology game is Norman > Ramsey's use of ``chunks'' in noweb. The word chunk carries no > ``excess baggage,'' ... > > -- Lee > leew@pilot.njin.net Hear! Hear! ``chunks'' is an excellent choice. As a matter of fact, ``chunks'' does carry a certain amount of background, but it is very appropriate in this case. The term ``chunk'' is often used in discussing how many items a person can keep in short-term memory at one time: the magic number 7 +/- 2 chunks, usually where each chunk is a single idea/concept/unit/... These chunks may be decomposed into smaller chunks, and will be different for different people. For example, an entire chessboard with pieces across it might be a single chunk to a chess master, while it might be several chunks for the rest of us. On the other hand, for an good programmer, a `push' or `pop' or even `bubble sort' might be a single chunk. Any of these chunks could be broken down into smaller chunks or steps later. The meaning carrys over nicely, because we can talk about a `chunk' of code as being a single unit, even if it is later broken down into further chunks. I really like the term `chunks,' and hereby go on record as recommending it for canonization as the _APPROVED_ term for the code fragments (with associated documentation, macros, etc.) which make up a WEB. -- Marcus Brown mbrown@cs.ua.edu Computer Science Dept, Univ of Alabama ================================================================================ Archive-Date: Tue, 19 Oct 1993 19:21:44 CST Sender: LP-Mgr@SHSU.edu From: shf@netcom.com (Stuart Ferguson) Reply-To: LitProg@SHSU.edu, shf@NETCOM.COM Subject: Re: Levels of Abstraction Message-ID: Date: Tue, 19 Oct 1993 21:40:49 GMT To: LitProg@SHSU.EDU +-- schrod@iti.informatik.th-darmstadt.de (Joachim Schrod) writes: | In article <>, shf@netcom.com (Stuart Ferguson) writes: | > It seemed like a step backwards to me to have a nicely typeset document | > describing a program and then have the code scraps contain untypeset | > comments in the code as if it were going to be read by a machine. [...] | Sorry, but I don't understand you. The inline comments of CWEB are of | course in TeX mode, and therefore you can make use of TeX markup | there as well. If it's good style (and good looking ;-) to put a I could easily be mistaken on this point, as I only looked at the Knuth articles for a short time. I was convinced that the inline comments were printed in teletype font between "/*" and "*/" with a very distracting word wrap. I'll go back and see if I can find that article again. In any case, the point is somewhat irrelevant, since CWEB apparently *does* support typeset inline comments. I'm pleased to hear this, since I think this is an important feature for literate C programing. -- Stuart Ferguson (shf@netcom.com) "Oh Dear Lord -- the canary exploded!" ================================================================================ Archive-Date: Wed, 20 Oct 1993 00:27:17 CST Sender: LP-Mgr@SHSU.edu From: bdubbs@cs.tamu.edu (Bruce Dubbs) Reply-To: LitProg@SHSU.edu, bdubbs@CS.TAMU.EDU Subject: Re: Inline comments and abstraction Date: 20 Oct 1993 04:32:45 GMT Message-ID: <2a2f1d$3a0@TAMUTS.TAMU.EDU> Keywords: commenting formatting abstraction To: LitProg@SHSU.EDU In article <2a0lj8INNl5d@rs18.hrz.th-darmstadt.de>, Joachim Schrod wrote: |In article <29v3ne$8l0@TAMUTS.TAMU.EDU>, bart@cs.tamu.edu (Bart Childs) writes: |> |> I also note that he called these small parts sections or modules. |> (He used the words interchangeably.) I think that is a far better |> term than scraps because they were intentional, not leftovers as |> in most of the definitions of scrap. | |I prefer the simple term `program part'. | |For me, section is ok most of the time, but sometimes one must stress |the difference between this `numbered entities' and their subparts. | |I _hate_ the term module. (In fact, Klaus and myself were one of the |pushers to delete this word of CWEB.) A module is an entity with a |distinct specification and implementation. One does not find this |distinction in WEB. The concept of a module, first outlined by |Parnas, later refined by Dennis, Ehrig & Mahr, and nowadays |modernized by Booch, is a central one to all software engineering |activities. It has _nothing_ to do with these WEB pieces. Please, |don't throw away the CS terms we have worked so long for! | Personally, I like the term `block', although `chunk' is OK too. Actually, a block of code can be considered in direct correlation to the cognitive chunks in psychology. -- Bruce |For what it's worth, here is a definition of terms I use usually: | | Before we start with an overview of the implementation I want to | explain the \cweb{} vocabulary I use while I guide you through this | document. The commonly used terms sometimes denote two entities, but | for the purpose of this style we need exact terms. I've tried to stick | to a ``canonical'' computer science terminology. | | \begin{quotation} | | I distinguish two different structures in a \cweb{} file: The {\sl | document structure\/} and the {\sl program structure}. | | A \cweb{} document consists of a series of {\sl sections}. Within | this series some sections are especially emphasized, we call them the | {\sl main sections}. (They are also called {\sl starred sections}, | since their corresponding \cweb{} tag is~|@*|.) These main sections | have a title, ordinary sections are untitled. A table of contents may | therefore list only the main sections. Note that there is no | hierarchy in the sections, they are all on the same level, ie, they | are numbered subsequently. | | Each section consists of three parts: (1)~the {\sl documentation | part}, (2)~the {\sl definition part}, and (3)~the {\sl program part}. | Each of these parts can be empty. The documentation part is mostly text | with \LaTeX{} tags. In this text material from {\sl restricted program | mode\/} can appear. The definition part consists of a series of either | {\sl macro\/} or {\sl format definitions}. The program part is one | piece of a refinement, identified by a name (see below). | | A \cweb{} program consists of a tree of {\sl refinements}. A | refinement is a list of program parts with the same name, ordered in | appearence. The root of the tree is the refinement with the special | name~|@c|. The program text is defined by the DFS (ie, infix-order) | traversal of the tree. | | \end{quotation} | | \noindent The terminology outlined above is an overspecification for | the \LaTeX{} style we're implementing here---nevertheless, the | context of my explanation should be clear now.% | |(That's a verbatim copy from the cweb style.) | |Any critic? comments? | |-- |Joachim | |=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= |Joachim Schrod Email: schrod@iti.informatik.th-darmstadt.de |Computer Science Department |Technical University of Darmstadt, Germany | | ``Real programmers can write Fortran in any language.'' [... Well,] | Real interface programmers can implement vi in any software envionment. | [Hartson, Brandenburg, Hix] -- Bruce Dubbs | Oxymorons of note: | Honest Politician, Political Science, bdubbs@hal.kelly.af.mil | Scrupulous Lawyer ================================================================================ Archive-Date: Wed, 20 Oct 1993 03:37:54 CST Sender: LP-Mgr@SHSU.edu Date: Wed, 20 Oct 1993 09:14 +0000 (GMT) From: "Eric W. van Ammers, LUW, tel: (+31)8370-83356" Reply-To: LitProg@SHSU.edu, AMMERS@RCL.WAU.NL Subject: Re: Inline comments and abstraction To: LitProg@SHSU.edu Message-ID: <01H4BWI5L0KK8ZJGS2@RCL.WAU.NL> Content-Transfer-Encoding: 7BIT Lee writes: ............ >However, my hands down favorite in the terminology game is Norman >Ramsey's use of ``chunks'' in noweb. The word chunk carries no >``excess baggage,'' as to both module and section (the former in >programming, the latter in word processing). It's unambiguous to >speak of ``code chunks'' and ``text chunks'' and the terms are readily >understandable. Chunk also has the advantage that it's only one >syllable, and therefore, easier to say. ......... There is another, much more important reason to standarize on the use of the word "chunk". Psychologist use "chunk" to identify the mental units one manipulates in his/her wetware (brain) when we are thinking. In a literate program we try to document individually the chunks that play a role in understanding a program. Eric ============================================================================ 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: Wed, 20 Oct 1993 03:59:39 CST Sender: LP-Mgr@SHSU.edu From: Mark.Probert@nms.otc.com.au (Mark Probert) Reply-To: LitProg@SHSU.edu, Mark.Probert@NMS.OTC.COM.AU Message-ID: <9310200858.AA07157@nmstms1.pad.otc.com.au> Subject: Re: cf. Chuck Moore, VLSI, Forth To: LitProg@SHSU.edu, preston@cs.rice.edu Date: Wed, 20 Oct 93 19:00:33 GMT Preston Briggs... > > Chuck Moore invented Forth. Doesn't have much to do with > literate programming. He also designed one (or more?) > micros intendedespecially to run Forth well. > I don't believe they actually had a compiler built in; > rather, they had exactly the registers and stacks required to > run a Forth interpreter efficiently, and no more. > The only ``commercial'' micro made was the Harris RTX2000, which used Forth as it microcode. All of the basic words you needed were there in ``hardware'' with optimised stack access. Great chip for it's day, pity Harris axed it so quickly. > > Enquire on comp.arch or comp.lang.forth for details. > Yep. -- mark. (probertm@nms.otc.com.au) ph: (02) 339 3705 fax: (02) 339 3917 ================================================================================ Archive-Date: Wed, 20 Oct 1993 06:07:57 CST Sender: LP-Mgr@SHSU.edu From: conrado@lsi.upc.es (Conrado Martinez-Parra) Subject: prettyprinting Message-ID: Reply-To: LitProg@SHSU.edu, conrado@lsi.upc.es Date: Wed, 20 Oct 1993 09:03:50 GMT To: LitProg@SHSU.EDU Hello, In my opinion, prettyprinting can be a useful feature but it is not necessary to provide it as a built-in feature of a WEB system. What is really needed is that the WEB system produces intermediate files, with standard 'formats'. Different specialized tools can then work on the appropriate file to generate xrefs, indexes, prettyprinted (pp) output, etc. This is the kind of approach that Norman Ramsey used in his noweb system, and it is the right one, in my opinion. If one likes pp, the only thing that is needed is a program that takes the weave'd file and includes pp macros in the code sections. If you don't like pp, don't use the pp program. I will use a particular example to make clear what I mean. Suppose we are working with noweb and LaTeX. After weaving the web file (.nw), one obtains a LaTeX file (.tex) where the code goes inside 'code' environments, for example, \begin{code}{} ... int gcd(int x, int y) { while (x != y) ... } \end{code} This 'code' environment is very similar to the standard 'verbatim' environment and therefore you'll not have pp output. The pp tool takes this LaTeX file as input, leaves everything outside the 'code' environments untouched and includes the pp macros within the code sections: \begin{ppcode}{} ... |int|\ |gcd|(|int| x, |int| y) \{ \while (x \ne y) ... \end{ppcode} I have developed such a 'ppcode' environment and the pp program for Dijkstra's command language. The pipeline 'noweb | d2tex' works rather well (although, it is a Beta version and the pp output sometimes looks terrible :-) ). Finally, it seems to me that a tool for generating such prettyprinters would be very useful and not very difficult to produce (the Spidery WEB system includes, in some sense, such a generator, doesn't it?). Conrado. --- +-------------------------------+--------------------------------+ | Conrado Martinez-Parra | Dept. of Software (LSI) | | e-mail : conrado@lsi.upc.es | Univ. Politecnica de Catalunya | | phone: (34-3) 401-73-36 | Pau Gargallo, 5 | | fax: (34-3) 401-70-14 | E-08028 Barcelona, Spain | +-------------------------------+--------------------------------+ ================================================================================ Archive-Date: Wed, 20 Oct 1993 07:22:15 CST Sender: LP-Mgr@SHSU.edu From: schrod@iti.informatik.th-darmstadt.de (Joachim Schrod) Reply-To: LitProg@SHSU.edu, schrod@ITI.INFORMATIK.TH-DARMSTADT.DE Subject: Re: Revision Control Date: 20 Oct 1993 11:49:31 GMT Message-ID: <2a38kbINN11ta@rs18.hrz.th-darmstadt.de> To: LitProg@SHSU.EDU In article , Lee Wittenberg writes: > A number of people have remarked on the rcs.sty file I mentioned in > one of my messages. Until now, I didn't know there was more than one. > The one I was referring to is by Tom Verhoeff ARGHHH! The 4th one... -- Joachim ================================================================================ Archive-Date: Wed, 20 Oct 1993 11:52:22 CST Sender: LP-Mgr@SHSU.edu From: wstomv@wsinpa04.win.tue.nl (Tom Verhoeff) Reply-To: LitProg@SHSU.edu, wstomv@WSINPA04.WIN.TUE.NL Subject: Re: Revision Control Date: 20 Oct 1993 16:59:58 +0100 Message-ID: <2a3n9u$co4@wsinpa04.win.tue.nl> To: LitProg@SHSU.EDU In article , Lee Wittenberg wrote: >A number of people have remarked on the rcs.sty file I mentioned in >one of my messages. Until now, I didn't know there was more than one. >The one I was referring to is by Tom Verhoeff, and boils down to the >following 2 definitions: > >\def\RCSdef $#1${\typeout{RCS keyword string: $#1$}\RCS@def#1: {} :.} >\def\RCS@def#1: #2 :#3.{\expandafter\def\csname RCS#1\endcsname{#2}} The definitions are very concise (and sort of unreadable). Here are (i) the condensed style file and (ii) its fully documented version. (By the way, it is mentioned in the TeX-index maintained (?) by David Jones .) ----- (i) condensed version of RCS.sty ----- % This style file, RCS.sty, is for use with RCS (a Revision Control System). % % Author: Tom Verhoeff, Dept. of Math. & C.S., Eindhoven Univ. of Technology % E-mail: wstomv@win.tue.nl % \def\filedate {1 July 1992} % \typeout{Documentstyle option `RCS': RCS keyword defines <\filedate>.} % % DOCUMENTATION in RCS.doc % \def\RCSdef $#1${\typeout{RCS keyword string: $#1$}\RCS@def#1: {} :.} \def\RCS@def#1: #2 :#3.{\expandafter\def\csname RCS#1\endcsname{#2}} % % END of RCS.sty ----- (ii) fully documented version of RCS.sty ----- % This style file, RCS.sty, is for use with RCS (a Revision Control System). % % Author: Tom Verhoeff, Dept. of Math. & C.S., Eindhoven Univ. of Technology % E-mail: wstomv@win.tue.nl % \def\filedate {1 July 1992} % \typeout{Documentstyle option `RCS': RCS keyword defines <\filedate>.} % % % PURPOSE % % Make it possible to include RCS (Revision Control System) keyword strings % (also called identification markers) in a LaTeX document such that % the keyword values can be referred to in the document. % % % USAGE % % In the LaTeX document, include `RCS' among the document style options: % \documentstyle[...,RCS,...]{...} % % Include an RCS keyword string in the document as: % \RCSdef $$ % or % \RCSdef $: $ % where is a nonempty value string. Note the spaces around . % The keyword string is echoed to the log file. % % Refer to the value of keyword as: % \RCS % % For a list of valid RCS keyword strings see the manual page of co(1). % % % EXAMPLE % % To have RCS maintain the revision number of a file inside that file % one acts as follows. Include the keyword string % % $Revision$ % % in the initial version of the file and submit the file to RCS by the % check-in command ci(1). The check-out command co(1) subsequently % replaces this string by % % $Revision: value $ % % where value is the current revision number of the file. % % Here is a LaTeX document that defines two RCS keyword strings, viz. % for a revision number and a revision date, and that prints the % revision date and number on the title page: % % \documentstyle[RCS]{article} % \RCSdef $Revision$ % \RCSdef $Date$ % \title{Usage Example of RCS Style Option} % \author{Tom Verhoeff} % \date{\RCSDate (Rev.\ \RCSRevision)} % \begin{document} % \maketitle % Test of RCS style option. % \end{document} % % % MOTIVATION % % Two trivial---but problematic---ways to include RCS keyword strings in % LaTeX source files are the following. % % 1. Put the keyword string in a TeX comment, i.e. following a percent % sign (`%'). For instance, % % % $Date$ % % $Revision$ % % 2. Put the keyword string in a place where you want the value printed. % For instance, in the title page definition of a LaTeX document write % % \date{$Date$ $Revision$} % % The problem with the first approach is that the keyword value is no % longer available for TeX processing (such as printing). % In the second approach you have to live with the fact that TeX processes % the keyword string in math mode and includes both the keyword string % identifier and its current value. % % Our solution is the following. Define a macro that takes the keyword % string as argument and that assigns the value to a control sequence % whose name is derived from the string's identifier. % % % IMPLEMENTATION DETAILS % % \RCSdef takes arguments of the form % $Keyword$ % or % $Keyword: value $ % The first form is a special case of the second with empty value string. % N.B. * There is a space after the colon (`:') AND another one before % the closing dollar-sign (`$'). % * The dollar-signs act as argument delimiters; do NOT use braces. % % \RCSdef strips the enclosing dollar-signs and invokes \RCS@def to % define the control sequence \RCSKeyword as value. % % More precisely, % \RCSdef $Keyword$ % expands to % \RCS@def Keyword: {} :. % And % \RCSdef $Keyword: value $ % expands to % \RCS@def Keyword: value : {} :. % % \RCS@def takes arguments of the form % Keyword: value :garbage. % and defines \RCSKeyword as value. % % For example, % \RCSdef $Revision$ % translates into % \def\RCSRevision{} % And % \RCSdef $Revision: 1.2 $ % translates into % \def\RCSRevision{1.2} % % This way one can embed RCS keyword strings in a LaTeX source file and % use their values as well. For instance, when including % \RCSdef $Revision$ % in the initial version of a LaTeX source, one can use \RCSRevision % in a header or footer to produce the current revision number. % The command co(1) updates the keyword string with a new value to reflect % changes. Re-LaTeX-ing propagates the changes into you document. % N.B. The command co(1) includes the appropriate spaces around value. % % WARNING: Do NOT write % \RCSdef $Revision:$ % since occurrence of the colon (`:') requires two additional spaces (` '). % Because TeX lumps consecutive spaces in the input into a single space, % writing % \RCSdef $Revision: $ % does not work. Control spaces (`\ ') do not work either because they % differ % from ordinary spaces. An empty value string could be written as % \RCSdef $Revision: {} $ % However, there is no need for this form, since $Revision$ is preferred. % % % TEX CODE % \def\RCSdef $#1${\typeout{RCS keyword string: $#1$}\RCS@def#1: {} :.} \def\RCS@def#1: #2 :#3.{\expandafter\def\csname RCS#1\endcsname{#2}} % % END of RCS.sty -- INTERNET: wstomv@win.tue.nl / Eindhoven University of Technology VOICE: +31 40 47 41 25 / Dept of Mathematics & Computing Science FAX: +31 40 43 66 85 / PO Box 513, NL-5600 MB Eindhoven, Netherlands ================================================================================ Archive-Date: Wed, 20 Oct 1993 13:52:14 CST Sender: LP-Mgr@SHSU.edu From: "Thompson, David" Reply-To: LitProg@SHSU.edu, dthompson@COE2.COE.TTU.EDU To: LitProg Subject: literate programming faq Date: Wed, 20 Oct 93 13:14:00 PDT Message-ID: <2CC59C16@cpds01.coe.ttu.edu> I've posted the first version of the literate programming faq on the faq-server. It should be forthcoming within the next day or so. I solicit your comments, and request that you understand the rough nature of the document. It will mature, but it takes time. Also, thanks to all of you who helped make the faq possible. See the document for a specific listing of individuals. -=d ======================================================================= David B. Thompson internet: wqdbt@ttacs1.ttu.edu Civil Engineering Dept. internet: dthompson@coe2.coe.ttu.edu Texas Tech University internet: thompson@sun1.coe.ttu.edu P.O. Box 41023 Lubbock, Texas 79409-1023 "Get a haircut and get a *real* job." ======================================================================= ================================================================================ Archive-Date: Wed, 20 Oct 1993 16:14:29 CST Sender: LP-Mgr@SHSU.edu From: schrod@iti.informatik.th-darmstadt.de (Joachim Schrod) Reply-To: LitProg@SHSU.edu, schrod@ITI.INFORMATIK.TH-DARMSTADT.DE Subject: Re: Inline comments and abstraction Date: 20 Oct 1993 20:29:25 GMT Message-ID: <2a4735INN11fi@rs18.hrz.th-darmstadt.de> To: LitProg@SHSU.EDU In article <9310192312.AA22346@athos.cs.ua.edu>, mbrown@athos.cs.ua.edu (Marcus Brown) writes: > > I really like the term `chunks,' and hereby go on record as > recommending it for canonization as the _APPROVED_ term for the code > fragments (with associated documentation, macros, etc.) which make up > a WEB. I like the term `chunks', too. But, not as a replacement for `section' -- as a replacement for `program part'. Or did I misunderstand you, and you talk about the same? Nevertheless, I would also like to keep the term `refinement' as a notion for the catenation of all chunks with the same name. I.e., for one node in the tree that constitutes the `real' source, after all. I think the disctinction is important, since we're on different abstraction levels here. -- Joachim =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= Joachim Schrod Email: schrod@iti.informatik.th-darmstadt.de Computer Science Department Technical University of Darmstadt, Germany When it comes to Literate Programming, I get irrational. --- DEK, 16 Jul 93 ================================================================================ Archive-Date: Wed, 20 Oct 1993 17:07:50 CST Sender: LP-Mgr@SHSU.edu Date: Wed, 20 Oct 1993 17:06:22 CST From: "George D. Greenwade" Reply-To: LitProg@SHSU.edu, bed_gdg@SHSU.EDU To: LitProg@SHSU.edu, schrod@ITI.INFORMATIK.TH-DARMSTADT.DE Message-ID: <009744F3.E6A62960.18141@SHSU.edu> Subject: Re: Revision Control On 19 Oct 1993 21:33:36 GMT, schrod@iti.informatik.th-darmstadt.de (Joachim Schrod) posted: > (My style option will be available from latex/contrib/rcs after > one of the CTAN managers has answered my question posed a month ago. > Hint, hint... ;-) Currently, you can fetch it from > ftp.th-darmstadt.de:pub/tex/latex/. Hmmmmmm. I guess I missed your question -- sorry. I have no idea what it was and quite honestly have no idea where I would have filed it away (it isn't in my file I keep on you, Joachim). If anyone ever needs to get to me about the CTAN here (or whoever might be watching it for me in my absence, assuming I ever get a vacation), you can post to: CTAN-Mgr@SHSU.edu Alternately, we have a list which only has the people directly involved in the CTAN subscribed to but which is open for posts from anyone anywhere -- you can post to and get everyone's attention whose attention needs getting to. To post to it, use the address: CTAN@SHSU.edu Regards, George %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% George D. Greenwade, Ph.D. Bitnet: BED_GDG@SHSU Department of Economics and Business Analysis THEnet: SHSU::BED_GDG College of Business Administration Voice: (409) 294-1266 P. O. Box 2118 FAX: (409) 294-3612 Sam Houston State University Internet: bed_gdg@SHSU.edu Huntsville, TX 77341 bed_gdg%SHSU.decnet@relay.the.net %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% ================================================================================ Archive-Date: Wed, 20 Oct 1993 17:21:53 CST Sender: LP-Mgr@SHSU.edu Date: Wed, 20 Oct 1993 17:19:45 CST From: "George D. Greenwade" Reply-To: LitProg@SHSU.edu, bed_gdg@SHSU.EDU To: LitProg@SHSU.edu, norman@BELLCORE.COM Message-ID: <009744F5.C541A900.18205@SHSU.edu> Subject: Re: Literate Programming Examples On Tue, 19 Oct 93 18:49:07 -0400, posted: > I think it's high time we had a central repository of literate-programming > examples. I think CTAN is the natural place for it, but if CTAN isn't > interested, I'll ask my management if we can arrange something here. (The > problem is that our lawyers won't let us make an ftp area that is both > readable and writable, and it takes real staff hours to move things from an > incoming to a readable directory.) It isn't that the CTAN isn't interested (at least as far as SHSU is concerned w.r.t. interest anyway); instead (unless something's happened in the past few days I am unaware of), it's that the CTAN is quickly running out of space on the hosts. Right now, SHSU has about 1.27 gig of stuff on a 1.2 gig drive. I have another 2.4 gig of archive space coming Real Soon Now for our Unix host (and I've actually seen the purchase order and outbound requisition, so RSN may actually be RSN) and about .8 gig of that is already taken. I'm just hoping that the remaining 1.6 will be enough to get me through the next calendar year. Anyway, moral of the story for SHSU's leg of the CTAN, is that as soon as I have the space available, I will be going back to a proactive stance on adding things; however, until we can get some additional resources for the other hosts, I can't guarantee that the LitProg-related stuff can or will be propagated from SHSU to the other hosts. Until then, the only way I could support it would be by traversing multiple hosts, which I prefer not to do for a variety of reasons (but will if everyone feels it has to be done). --George %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% George D. Greenwade, Ph.D. Bitnet: BED_GDG@SHSU Department of Economics and Business Analysis THEnet: SHSU::BED_GDG College of Business Administration Voice: (409) 294-1266 P. O. Box 2118 FAX: (409) 294-3612 Sam Houston State University Internet: bed_gdg@SHSU.edu Huntsville, TX 77341 bed_gdg%SHSU.decnet@relay.the.net %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% ================================================================================ Archive-Date: Wed, 20 Oct 1993 22:00:46 CST Sender: LP-Mgr@SHSU.edu Message-ID: <9310210254.AA10215@mailee.bellcore.com> To: "George D. Greenwade" CC: LitProg@SHSU.edu Subject: Re: Literate Programming Examples Date: Wed, 20 Oct 93 22:54:10 -0400 From: norman@bellcore.com Reply-To: LitProg@SHSU.edu, norman@BELLCORE.COM > On Tue, 19 Oct 93 18:49:07 -0400, posted: > > I think it's high time we had a central repository of literate-programming > > examples. > [the CTAN is quickly running out of space on the hosts] > [I have another 2.4 gig of archive space coming Real Soon Now] > [I will be going back to a proactive stance] OK. If I understand correctly, you are willing to maintain an archive of examples at SHSU once your new disk arrives. Other CTAN sites might or might not mirror it depending on space consumption. If RSN doesn't arrive, or if people perceive a pressing need, I can probably arrange a temporary archive at Princeton. Norman ================================================================================ Archive-Date: Wed, 20 Oct 1993 22:07:34 CST Sender: LP-Mgr@SHSU.edu Date: Wed, 20 Oct 93 23:00:27 -0400 From: norman@bellcore.com (Norman Ramsey) Reply-To: LitProg@SHSU.edu, norman@BELLCORE.COM Message-ID: <9310210300.AA03589@flaubert.bellcore.com> To: LITPROG@SHSU.edu Subject: Prettyprinting While we're on the topic of prettprinting, has anyone found any good monospace fonts? The PostScript Courier fonts are *ugly*. I'm especially curious to know whether any METAFONT wizards out there have tried to use the META-ness to create monospace versions of Computer Modern Roman, Bold, and Text Italic. Norman ================================================================================ Archive-Date: Thu, 21 Oct 1993 09:01:36 CST Sender: LP-Mgr@SHSU.edu From: mbrown@athos.cs.ua.edu (Marcus Brown) Reply-To: LitProg@SHSU.edu, mbrown@ATHOS.CS.UA.EDU Message-ID: <9310211358.AA13795@athos.cs.ua.edu> Subject: Re: Inline comments and abstraction To: LitProg@SHSU.edu, schrod@ITI.INFORMATIK.TH-DARMSTADT.DE Date: Thu, 21 Oct 1993 08:58:34 -0500 (CDT) Content-Type: text Joachim Schrod wrote: > > In article <9310192312.AA22346@athos.cs.ua.edu>, mbrown@athos.cs.ua.edu (Marcus Brown) writes: > > > > I really like the term `chunks,' ... > > I like the term `chunks', too. But, not as a replacement for `section' > -- as a replacement for `program part'. Or did I misunderstand you, > and you talk about the same? > [Stuff deleted] > -- > Joachim > I would like to use the term in referring to both the program part and the associated documentation. After all, in a 'Literate' program, the code is not complete without the accompanying documentation, etc. However, I would not object to the term being used specifically with reference to the code alone. -- Marcus Brown mbrown@cs.ua.edu Computer Science Dept, Univ of Alabama ================================================================================ Archive-Date: Thu, 21 Oct 1993 10:09:05 CST Sender: LP-Mgr@SHSU.edu Date: Thu, 21 Oct 93 11:07:25 -0400 From: koopman@sgi84.ctc.com (Michael G. Koopman) Message-ID: <9310211507.AA10188@sgi84.ctc.com> To: LitProg@SHSU.edu, mbrown@ATHOS.CS.UA.EDU CC: LitProg@SHSU.edu, schrod@ITI.INFORMATIK.TH-DARMSTADT.DE Subject: Inline comments and abstraction Reply-To: LitProg@SHSU.edu, koopman@ctc.com Marcus Brown wrote: >Joachim Schrod wrote: >> I like the term `chunks', too. But, not as a replacement for `section' >> -- as a replacement for `program part'. Or did I misunderstand you, >> and you talk about the same? >> >I would like to use the term in referring to both the program part >and the associated documentation. After all, in a 'Literate' program, >the code is not complete without the accompanying documentation, etc. > >However, I would not object to the term being used specifically with >reference to the code alone. How about chunklet for the code or documentation part. Cryptic code or poor documentation could be "dark" chunklet and code that took forever to write could be "milk" chunklet. Mike ================================================================================ Archive-Date: Thu, 21 Oct 1993 12:45:36 CST Sender: LP-Mgr@SHSU.edu Date: Thu, 21 Oct 93 13:42:32 EDT From: Lee Wittenberg Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET To: LitProg@shsu.edu, norman@bellcore.com Subject: Re: Prettyprinting Message-ID: Norman Ramsey asks: > While we're on the topic of prettprinting, has anyone found any good > monospace fonts? The PostScript Courier fonts are *ugly*. I'm especially > curious to know whether any METAFONT wizards out there have tried to > use the META-ness to create monospace versions of Computer Modern Roman, > Bold, and Text Italic. There's a really nice monospaced PostScript font that came with our NeXT machine. It's named after the guy who designed it, but I forget who (and the machine's half-way across campus). I can check it out if no one else knows. -- Lee leew@pilot.njin.net ================================================================================ Archive-Date: Thu, 21 Oct 1993 13:27:22 CST Sender: LP-Mgr@SHSU.edu Date: Thu, 21 Oct 93 13:37:40 EDT From: Lee Wittenberg Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET To: LitProg@shsu.edu, schrod@iti.informatik.th-darmstadt.de Subject: Re: Inline comments and abstraction Message-ID: Joachim Schrod writes: > I like the term `chunks', too. But, not as a replacement for `section' > -- as a replacement for `program part'. Or did I misunderstand you, > and you talk about the same? Generally, I use `chunk' for program part, but the noweb documentation refers to ``text chunks'' and ``code chunks,'' and I use those terms as well. > Nevertheless, I would also like to keep the term `refinement' as a > notion for the catenation of all chunks with the same name. I.e., for > one node in the tree that constitutes the `real' source, after all. > I think the disctinction is important, since we're on different > abstraction levels here. That's a good point. I like the term `refinement' in this context. It works well with the way `refinement' is used in the ABC programming language. -- Lee leew@pilot.njin.net ================================================================================ Archive-Date: Thu, 21 Oct 1993 13:30:42 CST Sender: LP-Mgr@SHSU.edu From: thompson@sun1.coe.ttu.edu Subject: comp.programming.literate FAQ Date: 21 Oct 1993 00:00:21 -0400 Message-ID: Reply-To: LitProg@SHSU.edu, thompson@sun1.coe.ttu.edu To: LitProg@SHSU.EDU Archive-name: literate-progamming-faq Last-modified: 1993/10/15 Version: 1.0.1 Welcome to the Literate Programming Frequently Asked Questions List ------------------------------------------------------------------- This version was created Fri 10/15/1993 and should considered stale after 90 days. Information contained in this document is the best available at preparation. Disclaimer: "This FAQ is presented with no warranties or guarantees of ANY KIND including correctness or fitness for any particular purpose. The author of this document has attempted to verify correctness of the data contained herein; however, slip-ups can and do happen. If you use this data, you do so at your own risk." Copyright 1993 David B. Thompson. All rights reserved. Permission is granted to copy this document for free distribution so long as it remains intact and unmodified. = ====================================================================== * Introduction: --------------- This document is for new and experienced users of literate programming tools. The purpose is to explain the concept of literate programming and to provide a resource for locating files of interest to literate programmers and those interested in literate programming. The Literate Programming (LitProg) Frequently Asked Questions (FAQ) list is maintained by Dave Thompson, who can be reached at: thompson@sun1.coe.ttu.edu * Preferred mailing address for FAQ related comments/questions. dthompson@coe2.coe.ttu.edu * Preferred for purposes other than FAQ. wqdbt@ttacs1.ttu.edu * Forwarded to me. Comment and constructive criticism is welcome. Direct flames to /dev/null (or > nul if you're a msdos user! ;-) If you find an error, please report it. I'm particularly interested in establishing the locations of generally available literate programming tools. If you are the author of such a tool and wish to have it included in this list, please send email. Please note this is a work-in-progress. It is *not* complete, and probably will not be complete for some months. Nevertheless, the information contained herein may be useful to some. Use it as it is intended. - ---------------------------------------------------------------------- - Typography: ------------- Major sections of the FAQ are divided by double lines (====). Minor sections and other divisions are separated by single lines (----). Major topics use a "* " as a leader. Minor topics use a "- " as a leader. This should simplify searching for topics. = ====================================================================== Table of Contents: ------------------ * Introduction - Typography. * How to get the FAQ. - Literate Programming FAQ. - FWEB FAQ. * The LitProg newsgroup. * Internet nodes of interest to literate programmers. * What is literate programming? * How do I begin literate programming? * What tools are available and where are they? - FWEB - CWEB - NOWEB - NUWEB - FunnelWeb - SchemeWEB - c2latex * Languages supported with literate programming tools. * What other resources are available? * Code examples. - Cameron Smith's KR-CWEB - Bart Child's examples for FWEB - Examples with CWEB - Examples with FWEB * Bibliographies. * How to anonymously ftp. * Acknowledgements. * Notes. = ====================================================================== * How to get the FAQ: --------------------- - Literate Programming FAQ. --------------------------- You have many ways to get a current copy of this FAQ. One is to use anonymous ftp (if you don't know how, see a later section in this FAQ) to connect to one of the Comprehensive TeX Arvchive Network (CTAN) sites or the literate programming archive and retrieve a copy of the file. (For more information on CTAN and the literate programming archive, see the section below entitled "Internet Nodes of Interest to Literate Programmers.") An alternative is to use the fileserver at SHSU. Send a message to FILESERV@SHSU.EDU (FILESERV@SHSU.BITNET) and include in your message SENDME FAQ.LITPROG The file server will forward a copy of the file to you via email. - ---------------------------------------------------------------------- - FWEB FAQ: ----------- Marcus Speh maintains the FWEB FAQ. It can be retrieved in the same way as this FAQ; either by anonymous ftp or through the SHSU file server. On the SHSU server, the file name is FAQ.FWEB. Invoke your ftp software, open a connection to NIORD.SHSU.EDU [192.92.115.8], attach to the directory FAQ, and transfer the file FAQ.FWEB. Alternatively, send a message to the file server, FILESERV@SHSU.EDU (FILESERV@SHSU.BITNET), and include the following text in a one line message: SENDME FAQ.FWEB The file server will send the current version of the file via email. The FWEB FAQ exists in various formats, including HyperText (see other resources below). In Europe, the complete distribution can also be obtained from ftp.desy.de [131.169.10.38] in directory /pub/faq/web/fweb/. = ====================================================================== * The LitProg Newsgroup: ------------------------ One of the most important resources is the literate programming newsgroup, comp.programming.literate. You can read this newsgroup using your standard reader. Altenatively, the newsgroup is gated to a mailing list hosted by George Greenwade and Sam Houston State University. You can subscribe by sending mail to the list-server, LISTSERV@SHSU.EDU (or LISTSERV@SHSU.BITNET), and include in the message one line of text: SUBSCRIBE LITPROG "your name in quotes" The list is unmoderated; messages sent to litprog@shsu.edu are automatically distributed to all subscribers and cross-posted to comp.programming.literate. Archives of the mailing list and newsgroup are maintained on niord.shsu.edu [192.92.115.8] in the directory litprog. = ====================================================================== * Internet Nodes of Interest to Literate Programmers: ----------------------------------------------------- The principal nodes of interest to literate programmers are the Literate Programming Archive (LPA hereafter) and the CTAN (Comprehensive TeX Archive Network). The Literate Programming Archive is: Node: ftp.th-darmstadt.de [130.83.55.75] Directory: pub/programming/literate-programming Notes: Fastest response during off-U.S. [yep] business hours. The CTAN sites are: ftp host IP CTAN root Institution and Sponsor ------------------------------------------------------------------------- ftp.TeX.ac.UK 134.151.79.32 pub/archive Aston Univ./UK TeX U.G. ftp.Uni-Stuttgart.DE 129.69.1.12 soft/tex Univ. Stuttgart/DANTE e.V ftp.SHSU.edu 192.92.115.10 tex-archive Sam Houston State Univ. Other nodes and directories of interest include: Node: niord.shsu.edu [192.92.115.8] Directory: various (do some snooping!) Notes: Has a gopher server. Node: ftp.desy.de [131.169.10.38] Directory: pub/web. Various documents, samples, and the FWEB FAQ. Notes: Has a www server, http://info.desy.de:80/ = ====================================================================== * What is Literate Programming? ------------------------------- Literate programming is the combination of documentation and source together in a fashion suited for reading by human beings. In fact, literate programs should be enjoyable reading, even inviting! (Sorry Bob, I couldn't resist!) In general, literate programs combine source and documentation in a single file. Literate programming tools then parse the file to produce either readable documentation or compilable source. The WEB style of literate programming was created by D.E. Knuth during the development of his TeX typsetting software. All the original work revolves around a particular literate programming tool called WEB. Knuth says: The philosophy behind WEB is that an experienced system programmer, who wants to provide the best possible documentation of his or her software products, needs two things simultaneously: a language like TeX for formatting, and a language like C for programming. Neither type of language can provide the best documentation by itself; but when both are appropriately combined, we obtain a system that is much more useful than either language separately. The structure of a software program may be thought of as a web that is made up of many interconnected pieces. To document such a program we want to explain each individual part of the web and how it relates to its neighbours. The typographic tools provided by TeX give us an opportunity to explain the local structure of each part by making that structure visible, and the programming tools provided by languages such as C or Fortran make it possible for us to specify the algorithms formally and unambigously. By combining the two, we can develop a style of programming that maximizes our ability to perceive the structure of a complex piece of software, and at the same time the documented programs can be mechanically translated into a working software system that matches the documentation. = ====================================================================== * How to begin literate programming: ------------------------------------ A recommended book is Wayne Sewell's (1989) "Weaving a Program: Literate Programming in WEB," Van Nostrand Reinhold, ISBN 0-442-31946-0 (pbk). Another 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 is more of historical interest than Sewell's book, but is a good read. Some talk exists in the newsgroup/mailing list for a Usenet University course in literate programming. I'm sure discussion of this topic will be welcomed. If you are interested, please participate. = ====================================================================== * What Tools are Available: --------------------------- A significant number of tools for literate programming are available. Most have been ported from their original systems, so support multiple computer platforms. If you are the developer of such a tool, and would like to make the software freely available, please send me email and I'll reply with a form (like those below) for you to fill in. (Or short-circuit the process and kludge a form from below. :-) - FWEB: ------- Developer: John A. Krommes System(s) supported: Unix and DOS platforms Software supported: C, C++, Fortran-77, Fortran-90, Ratfor, TeX, and LaTeX. Availability: anonymous ftp from lyman.pppl.gov/pub/fweb anonymous ftp from CTAN/web/fweb anonymous ftp from LPA/machines/ms-dos Readme: In bundle with above. Brief description: It also has a well-developed user's manual and its own FAQ (see above). It runs on most platforms: VMS, PC, UNIX, and pretty much anything that the GNU C compiler (GCC) is supported for. Support: bug reports to krommes@princeton.edu - ---------------------------------------------------------------------- - CWEB: ------- Developer: Silvio Levy and D.E. Knuth System(s) supported: Unix systems (dos port available) Software supported: C, C++, TeX, and LaTeX. Availability: anonymous ftp from labrea.stanford.edu/pub/cweb anonymous ftp from CTAN/web/c_cpp/cweb anonymous ftp from CTAN/web/c_cpp/cwb30p8c (dos version) Readme: bundled with above Brief description: Support: bugs to levy@math.berkeley.edu - ---------------------------------------------------------------------- - NOWEB: -------- Developer: Norman Ramsey System(s) supported: Unix and DOS platforms Software supported: All programming languages, (La)TeX formatters. Availability: anonymous ftp from csservices.princeton.edu/pub/noweb.shar.Z anonymous ftp from bellcore.com/pub/norman/noweb.shar.Z Readme: with bundle above Brief description: noweb is designed to meet the needs of literate programmers while remaining as simple as possible. Its primary advantages are simplicity, extensibility, and language-independence. noweb uses 4 control sequences to WEB's 27, and its manual is only two pages. noweb works ``out of the box'' with any programming language, and its formatter-dependent part is under 50 lines. The primary sacrifice relative to WEB is the loss of the language-dependent features: prettyprinting and an index of identifiers. Support: by email to the author - ---------------------------------------------------------------------- - NUWEB: -------- Developer: Preston Briggs: preston@cs.rice.edu Systems supported: Unix systems; Sparcs, RS/6000s, HPs, and (!) MSDOS. Software supported: It's written in C. It works with any programming language (or combination of programming languages) and Latex Availability: anonymous ftp from CTAN/web/nuweb (UNIX) anonymous ftp from CTAN/web/nuweb-pc (MSDOS) anonymous ftp from LPA Readme: Send mail to preston@cs.rice.edu Brief description: A single program that takes a web file written in a combination of latex and any programming language(s) and produces a latex file that can be pretty printed and a set of files containing code for compilation/interpretation by the appropriate language processors. Strengths include speed, simplicity, multiple languages, nice indices and cross-references, latex. Doesn't require any special macros or macro files. Drawbacks: latex-dependent, no code pretty printing, harder to make indices than cweb. More good stuff: nice support for make, doesn't reformat source files, so they're easy to debug. Lots of control without too much effort. That is, it doesn't do too much! Future directions... Very little change planned, except perhaps refinements in the indexing software. Support: Hack it yourself or send e-mail to preston@cs.rice.edu - ---------------------------------------------------------------------- - FunnelWeb: ------------ Developer: Ross N. Williams: ross@guest.adelaide.edu.au Systems supported: MSDOS, Mac, VMS, Sun. Other ports reported. Software supported: For printing, TeX. Otherwise no restrictions. Availability: anonymous ftp from CTAN/web/funnelweb anonymous ftp from ftp.adelaide.edu/pub/funnelweb Readme: With bundle above. Brief description: FunnelWeb is a production-quality literate-programming tool that emphasises simplicity and reliability. Everything about FunnelWeb, from the simplicity of its language to the comprehensive tutorial in the user's manual, has been designed to make this as simple, as practical, and as usable a tool as possible. Features: + Provides a simple macro preprocessor facility. + Can produce typeset documentation. + Runs on Sun, VMS VAX, Macintosh, PC, and others. + Portable C source code distributed under GNU licence. + Comprehensive user's manual including tutorial. + Programming-language independent. + Can generate multiple output files. + Allows complete control over the output text. + Regression test suite with over 200 tests. + Fully worked example (in /pub/funnelweb/examples). - Requires TeX to produce typeset documentation. - Typesets program code using TT font only. Support: No formal support available. Mailing list maintained with about 50 subscribers. Informal assistance available from mailing list. - ---------------------------------------------------------------------- - SchemeWEB: ------------ Developer: John D. Ramsdell System(s) supported: Unix and DOS platforms Software supported: Programming language: Any dialect of Lisp. Text formatter: LaTeX. Availability: The Unix version is in the Scheme Repository and it is available via anonymous ftp from nexus.yorku.ca in /pub/scheme/utl. The DOS version is part of the PCS/Geneva Scheme system which is available via anonymous ftp from cui.unige.ch in /pub/pcs. Readme: In bundle with above. Brief description: SchemeWEB is a Unix or DOS filter that translates SchemeWEB source into LaTeX source or Lisp source. Lisp code is formatted in typewriter type font and the comments are passed to LaTeX unchanged. Support: Send bug reports to ramsdell@mitre.org. - ---------------------------------------------------------------------- - C2LaTeX: ---------- Developer: John D. Ramsdell System(s) supported: Unix Software supported: Programming language: C. Text formatter: LaTeX but it's easy to change the formatter. Availability: Anonymous ftp from omnigate.clarkson.edu:/pub/tex/tex-programs/c2latex. Readme: Absent. Documentation is in the C source for c2latex. Brief description: C2latex provides simple support for literate programming in C. Given a C source file in which the comments have been written in LaTeX, c2latex converts the C source file into a LaTeX source file. It can be used to produce typeset listings of C programs and/or documentation associated with the program. C2latex produces LaTeX source by implementing a small number of rules. A C comment that starts at the beginning of a line is copied unmodified into the LaTeX source file. Otherwise, non-blank lines are surrounded by a pair of formatting commands (\begin{flushleft} and \end{flushleft}), and the lines are separated by \\*. Each non-blank line is formatted using LaTeX's \verb command, except comments within the line are formatted in an \mbox. Support: Send bug reports to ramsdell@mitre.org. = ====================================================================== * Other resources: ------------------ An untapped resource (by me anyway ;-) is the World Wide Web. Marcus Speh has expended considerable effort in this regard. If you're connected to WWW, then access: http://info.desy.de/pub/www/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/pub/www/projects/LitProg.html Help for people who have only Email and neither WWW nor telnet, can be obtained by Email from LISTSERV@INFO.CERN.CH by sending a message containing the command HELP. Instructions will be returned by email. For literate programming documents, you can try anonymous ftp to ftp.desy.de [131.169.30.33] and attach to directory: /pub/www/projects/Announce Another resource of interest to literate programmers is the info-tex mailing list. If you're using (La)TeX as your typsetting system and have access to internet, then you should investigate this mailing list. Mail list service is available through the SHSU list-server. To subscribe, send a message to LISTSERV@SHSU.EDU (LISTSERV@SHSU.BITNET), and include in the message one line of text: SUBSCRIBE INFO-TEX "your name in quotes" The list is unmoderated; messages sent to info-tex@shsu.edu are automatically distributed to all subscribers and cross-posted to comp.text.tex. Archives of the mailing list and newsgroup are maintained on niord.shsu.edu [192.92.115.8] in the directory info-tex. = ====================================================================== * Code Examples: ---------------- Examples of web programs are included with the FWEB distribution. Also, demonstration programs are included with the CWEB distribution. Bart Childs converted the K&R calculator program into a literate program. It can be retrieved from niord.shsu.edu [192.92.115.8] from directory kr-cweb-sample as krcwsamp.zip. Ross Williams has released a funnelweb example. You can retrieve this file from node ftp.adelaide.edu.au [129.127.40.3] as /pub/funnelweb/examples/except.* This file should be on CTAN as well. = ====================================================================== * Bibliographies: ----------------- Nelson Beebe has collected an extensive bibliography treating literate programming. His work is available for anonymous ftp from ftp.math.utah.edu [128.110.198.2] in directory /pub/tex/bib as files: litprog.bib litprog.ltx. Although I have not verified this, LPA is an alternate source for these files. Note that they are updated frequently (Nelson says several times each week), so be sure to get a fresh copy before extensive use. Joachim Schrod indicates that these files may be updated daily and can be retrieved via anonymous ftp at LPA/documentation. = ====================================================================== * How to anonymously ftp: ------------------------- Pretty much everything mentioned here is available by anonymous FTP. FAQ lists cross-posted to news.answers and rec.answers can be gotten from rtfm.mit.edu (18.70.0.224), 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 litprog.faq /* get the file; case-sensitive */ > quit /* stop this mysterious thing */ If your FTP program complains that it doesn't know where the site you want to use is, type the numerical address instead of the sitename: > ftp 18.70.0.224 /* 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 (PC) Extract with Zip or Unzip .zoo (PC) Yet another archive/compress program .lhe (Amiga) ? .exe (PC) 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. = ====================================================================== * Notes: -------- This document will be evolving over the next few months. I'm planning on adding entries for additional literate programming tools and will expand the sections on examples as more examples become available. Tools I will include are web (the original pascal version), funnelweb, spiderweb, and cnoweb for starters. Others will be added as I find and document them. Omission of a particular tool should not be considered a snub in any sense--simply an error or oversight on my part. History: First release: Fri 10/15/1993 -- Yep, I finally did it! = End of File ========================================================== ================================================================================ Archive-Date: Thu, 21 Oct 1993 15:44:58 CST Sender: LP-Mgr@SHSU.edu From: "Edward M. Robinson" Reply-To: LitProg@SHSU.edu, Robinson@UH.EDU Message-ID: <199310212043.AA18523@Menudo.UH.EDU> Subject: Re: Prettyprinting To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET Date: Thu, 21 Oct 1993 15:43:03 -0500 (CDT) MIME-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit Lee Wittenberg wrote : > >Norman Ramsey asks: >> While we're on the topic of prettprinting, has anyone found any good >> monospace fonts? The PostScript Courier fonts are *ugly*. I'm especially >> curious to know whether any METAFONT wizards out there have tried to >> use the META-ness to create monospace versions of Computer Modern Roman, >> Bold, and Text Italic. > >There's a really nice monospaced PostScript font that came with our >NeXT machine. It's named after the guy who designed it, but I forget >who (and the machine's half-way across campus). I can check it out if >no one else knows. The name is 'ohlfs'. Proprietary? -- Ed Robinson Robinson@uh.edu ================================================================================ Archive-Date: Thu, 21 Oct 1993 19:19:09 CST Sender: LP-Mgr@SHSU.edu From: cgra@se.alcbel.be (Chris Gray) Subject: Re: Prettyprinting Message-ID: <2146@se.alcbel.be> Date: 21 Oct 93 08:42:31 GMT Reply-To: LitProg@SHSU.edu, cgra@se.alcbel.be To: LitProg@SHSU.EDU In article <16721946@MVB.SAIC.COM>, norman@bellcore.com (Norman Ramsey) writes: >While we're on the topic of prettprinting, has anyone found any good >monospace fonts? The PostScript Courier fonts are *ugly*. I'm especially >curious to know whether any METAFONT wizards out there have tried to >use the META-ness to create monospace versions of Computer Modern Roman, >Bold, and Text Italic. >Norman Might not cmtt be a place to start?Or is that considered even uglier than Courier? (I've just bought the MF book. A bold or sloping cmtt should be a good practical exercise. When I get that round tuit I keep asking for.) __________________________________________________________________________ Chris Gray cgra@se.alcbel.be Compu$erve: 100065.2102 ================================================================================ Archive-Date: Thu, 21 Oct 1993 20:32:29 CST Sender: LP-Mgr@SHSU.edu From: greyham@research.canon.oz.au (Graham Stoney) Reply-To: LitProg@SHSU.edu, greyham@RESEARCH.CANON.OZ.AU Subject: c2man-2.17: Automatic C documentation generator is now under review. Message-ID: Keywords: c2man, troff, documentation, review Date: Thu, 21 Oct 1993 07:51:54 GMT To: LitProg@SHSU.EDU c2man is an automatic documentation generator which generates functional interface documentation from C source code and comments. Patches 10 thru 17 to c2man are currently under review in comp.sources.reviewed. If you are a C user and are interested in not having to write documentation manually, please consider reviewing these patches. With this new version of c2man, OS/2 and MSDOS are supported, and texinfo output can be generated in addition to the usual nroff -man. These patches will be posted after the review is complete and any significant problems have been addressed. If you fetch the package for review, please return your review in a timely manner, since the sooner the reviews are returned, the sooner the patches will be posted. If you are already using c2man at patchlevel 17, please consider sending in a review anyway. [comp.sources.reviewed Moderator's info] This package contains a C program to convert C source to `nroff -man' input, plus 7 patch files and a shell dirver to unpack the lot. This product has been reviewed and posted before. Check it out. If you are interested in *reviewing* this package send a mail message to the csr mail-server: To: csr@cc.purdue.edu Subject: send c2man and the mail server will send you the stuff. Initial comments: - I unpacked the parts, and applied the patches. - I include a script to do the same for you - I configured the product and it runs on sun4-sunos4.1.3. - you get 17 parts, but 3 of them are padding for the mail-server If you need help with the mail-server send a note like To: csr@cc.purdue.edu Subject: help Graham -- Graham Stoney, Hardware/Software Engineer Canon Information Systems Research Australia Ph: + 61 2 805 2909 Fax: + 61 2 805 2929 ================================================================================ Archive-Date: Thu, 21 Oct 1993 20:50:58 CST Sender: LP-Mgr@SHSU.edu From: detig@iti.informatik.th-darmstadt.de (Christine Detig) Reply-To: LitProg@SHSU.edu, detig@ITI.INFORMATIK.TH-DARMSTADT.DE Subject: Re: Inline comments and abstraction Date: 21 Oct 1993 15:41:40 GMT Message-ID: <2a6ajkINNkjf@rs18.hrz.th-darmstadt.de> Keywords: commenting formatting abstraction To: LitProg@SHSU.EDU In article <2a2f1d$3a0@TAMUTS.TAMU.EDU>, bdubbs@cs.tamu.edu (Bruce Dubbs) writes: > Personally, I like the term `block', although `chunk' is OK too. > Actually, a block of code can be considered in direct correlation to > the cognitive chunks in psychology. In many programming languages, `block' is used for parts of code which have a common scope. Thus, our chunks would in general spread over several blocks or contain only parts of them, which seems to make the term unappropriate to me. I think `chunk' is fine, but as a non-native speaker, I'm not sure if this word contains some sloppyness --- I mean, the kind of words you say but don't write. Could some native speakers, probably from both sides of the Atlantic, comment on this? Christine detig@iti.informatik.th-darmstadt.de =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= Good documentation, it seems, is like the weather: everyone is talking about it, but few people are doing anything about it. ================================================================================ Archive-Date: Thu, 21 Oct 1993 21:05:28 CST Sender: LP-Mgr@SHSU.edu From: creilly@maths.tcd.ie (Colman Reilly) Reply-To: LitProg@SHSU.edu, creilly@MATHS.TCD.IE Subject: Re: Inline comments and abstraction Date: 21 Oct 1993 17:12:34 +0100 Message-ID: <2a6cdi$9am@salmon.maths.tcd.ie> Keywords: commenting formatting abstraction To: LitProg@SHSU.EDU detig@iti.informatik.th-darmstadt.de (Christine Detig) writes: >I think `chunk' is fine, but as a non-native speaker, I'm not sure if >this word contains some sloppyness --- I mean, the kind of words you >say but don't write. Could some native speakers, probably from both >sides of the Atlantic, comment on this? Chunk is an execellent word to use actually, as it doesn't have any other technical meaning I'm aware of. As someone new to literate programming I found the word scrap very strange in this context - my code isn't a _scrap_ or leftover anything, no matter what my lecturers say. :-) Colman -- Colman Reilly (creilly@maths.tcd.ie) [+353-(0)1-7022280] c/o School of Mathematics,18.05 Westland Row,Trinity College,Dublin. PGP Public Key on Request "Nothing so strong as gentleness; nothing so gentle as real strength." ================================================================================ Archive-Date: Fri, 22 Oct 1993 06:20:14 CST Sender: LP-Mgr@SHSU.edu Date: Fri, 22 Oct 93 11:41 GMT0BST-1 From: Roger Horne Subject: Re: Prettyprinting To: litprog@shsu.edu Reply-To: LitProg@SHSU.edu, rhorne@cix.compulink.co.uk Message-ID: >> monospace fonts? The PostScript Courier fonts are *ugly*. >> I'm especially curious to know whether any METAFONT wizards >> out there have tried to use the META-ness to create >> monospace versions of Computer Modern Roman, Try changing monospace:=true to monospace:=false in eg cmr12.mf (and rename it to say cmr12m) and run Metafont on it. Voila, a monospaced cmr12. The result is interesting, but hardly pretty. (The letter m looks even more compressed than usual.) Roger Horne roger@number7.demon.co.uk ================================================================================ Archive-Date: Fri, 22 Oct 1993 09:26:58 CST Sender: LP-Mgr@SHSU.edu From: marcus@x4u2.desy.de (Marcus Speh) Reply-To: LitProg@SHSU.edu, marcus@X4U2.DESY.DE Subject: LitProg FAQ on WWW Message-ID: Date: Fri, 22 Oct 1993 14:01:34 GMT To: LitProg@SHSU.EDU I have put Dave Thompson's FAQ [recently posted to c.p.l.] on the World Wide Web, URL http://info.desy.de/pub/faq/web/FAQ.txt or (for the "collection" :-) http://info.desy.de/pub/www/projects/LitProg/FAQs.html For subsequent editions, I will also put a "diff" file to that place. -- ----------------------------------------------------------------------------- Marcus Speh, II.Inst.Theor.Physik,Luruper Chaussee 149, 22761 Hamburg,Germany Phone: +49-40 8998 2178, Fax: +49-40 8998 2267, Private: +49-40 801392 Internet: , ================================================================================ Archive-Date: Fri, 22 Oct 1993 10:22:35 CST Sender: LP-Mgr@SHSU.edu Date: Fri, 22 Oct 93 10:12:53 CDT From: "C. M. Sperberg-McQueen" Reply-To: LitProg@SHSU.edu, U35395%UICVM.BITNET@SHSU.EDU Subject: Re: Inline comments and abstraction To: LitProg@SHSU.edu, detig@ITI.INFORMATIK.TH-DARMSTADT.DE On 21 Oct 1993 15:41:40 GMT said: >I think `chunk' is fine, but as a non-native speaker, I'm not sure if >this word contains some sloppyness --- I mean, the kind of words you >say but don't write. Could some native speakers, probably from both >sides of the Atlantic, comment on this? I think your instinct is correct, Christine: at least to this native speaker of AmE, 'chunk' is marked for informality, and is more likely to be found in spoken than in formal written English. That is, of course, part of its appeal to some of us (me, I like 'scrap' even better, partly because it is an even less predictable term and partly because in the context I work in, 'chunk' has already been assigned a technical meaning as the name of a class of SGML elements). So it is not at all out of place in normal AmE computer science-type discourse, but it is perhaps the kind of word (like 'memory' and 'flavor') bound to meet with the disapproval of Edsger Dijkstra and others who share some of his less flexible notions concerning proper terminology. -C. M. Sperberg-McQueen ================================================================================ Archive-Date: Fri, 22 Oct 1993 15:20:43 CST Sender: LP-Mgr@SHSU.edu Message-ID: <9310221754.AA23314@mailee.bellcore.com> To: LitProg@SHSU.edu, U35395%UICVM.BITNET@SHSU.EDU Subject: Re: Inline comments and abstraction Date: Fri, 22 Oct 93 13:54:26 -0400 From: norman@bellcore.com Reply-To: LitProg@SHSU.edu, norman@BELLCORE.COM > [``chunk''] is perhaps > the kind of word (like 'memory' and 'flavor') bound to meet with the > disapproval of Edsger Dijkstra What stronger endorsement could anyone ask for? Norman ================================================================================ Archive-Date: Fri, 22 Oct 1993 15:28:35 CST Sender: LP-Mgr@SHSU.edu Date: Fri, 22 Oct 93 15:49:49 EDT From: Lee Wittenberg Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET To: LitProg@shsu.edu, detig@iti.informatik.th-darmstadt.de Subject: Re: Inline comments and abstraction Message-ID: Christine Detig writes: > I think `chunk' is fine, but as a non-native speaker, I'm not sure if > this word contains some sloppyness --- I mean, the kind of words you > say but don't write. Could some native speakers, probably from both > sides of the Atlantic, comment on this? As a native speaker (West Side of Atlantic/East Side of Pacific chapter -- we shouldn't forget the other ocean; native English speakers seem to like distancing themselves from each other :-), `chunk' has the right ring to my ears. However, having been born in Brooklyn, I might have to be disqualified. `Chunk' also works well on paper, having acquired legitimacy from Psychology (as a number of participants in this discussion have already pointed out). -- Lee ================================================================================ Archive-Date: Sat, 23 Oct 1993 11:04:01 CST Sender: LP-Mgr@SHSU.edu From: bdubbs@cs.tamu.edu (Bruce Dubbs) Reply-To: LitProg@SHSU.edu, bdubbs@CS.TAMU.EDU Subject: Re: Inline comments and abstraction Date: 23 Oct 1993 15:41:06 GMT Message-ID: <2abjai$965@TAMUTS.TAMU.EDU> To: LitProg@SHSU.EDU In article <16782125@mvb.saic.com>, Lee Wittenberg wrote: |Christine Detig writes: | |> I think `chunk' is fine, but as a non-native speaker, I'm not sure if |> this word contains some sloppyness --- I mean, the kind of words you |> say but don't write. Could some native speakers, probably from both |> sides of the Atlantic, comment on this? | |As a native speaker (West Side of Atlantic/East Side of Pacific chapter -- |we shouldn't forget the other ocean; native English speakers seem to |like distancing themselves from each other :-), `chunk' has the right |ring to my ears. However, having been born in Brooklyn, I might have to |be disqualified. | |`Chunk' also works well on paper, having acquired legitimacy from |Psychology (as a number of participants in this discussion have already |pointed out). | | -- Lee The problem with `chunk' is that it does have this use in Psychology. The more complete term is `cognitive chunk'. I have proposed the term `cognitve block' in a paper now being refereed. In writing code, using the style of literate programming or not, the author presents code in groupings. The degree of mapping of these groupings or `cognitive blocks' to the reader's psychological `cognitive chunks' really dictates the readability or understandability of the code. My research indicates that WEB style literate programming tends to provide a better mapping between blocks and chunks. -- Bruce -- R. Bruce Dubbs, Jr., Ph.D. email: bdubbs@tis.kelly.af.mil Mission Critical Software Division Kelly AFB, Tx ================================================================================ Archive-Date: Sun, 24 Oct 1993 08:06:27 CST Sender: LP-Mgr@SHSU.edu From: marcus@x4u2.desy.de (Marcus Speh) Reply-To: LitProg@SHSU.edu, marcus@X4U2.DESY.DE Subject: nuweb doesnt like Emacs outline-regexp Message-ID: Date: Sat, 23 Oct 1993 21:15:13 GMT To: LitProg@SHSU.EDU I have a little problem with nuweb. Since I am working in GNU Emacs, I'd like to use the outline mode [which all users of web-mode will appreciate]. Thus, I usually insert a line like % -*- Mode: outline; outline-regexp: "[@]"; eval: (hide-body); -*- [my actual mode line also uses regexps for LaTeX headings etc.] to be able to reduce the visible part of the document to something like @o file -t @{ ... @} @d HEADER @{ ... @} ... etc. Now, nuweb refuses to follow and aborts with nuweb: bad @ sequence (file.nu, line 1) There is no problem with that in noweb, where I am simple warned if I have "<<" in the mode-line for a possibly incomplete chunk def or a missing "=". I would wish nuweb would switch from error to warning too. Anybody ever ran into this problem? Is there a simple solution? -- ----------------------------------------------------------------------------- Marcus Speh, II.Inst.Theor.Physik,Luruper Chaussee 149, 22761 Hamburg,Germany Phone: +49-40 8998 2178, Fax: +49-40 8998 2267, Private: +49-40 801392 Internet: , ================================================================================ Archive-Date: Sun, 24 Oct 1993 08:13:48 CST Sender: LP-Mgr@SHSU.edu From: yjc@po.cwru.edu (Jerome Chan) Reply-To: LitProg@SHSU.edu, yjc@PO.CWRU.EDU Subject: CWeb for the Macintosh Date: Sat, 23 Oct 1993 23:19:27 -0500 Message-ID: To: LitProg@SHSU.EDU Where can I find any of these? I've looked into the FAQ list and I don't see it. :( -- The Evil Tofu (Only Human) ================================================================================ Archive-Date: Sun, 24 Oct 1993 08:24:03 CST Sender: LP-Mgr@SHSU.edu From: dmason@uwaterloo.ca (Dave Mason) Reply-To: LitProg@SHSU.edu, dmason@UWATERLOO.CA Subject: Luminary abuse (was Re: Inline comments and abstraction) Message-ID: Date: Sun, 24 Oct 1993 04:29:12 GMT To: LitProg@SHSU.EDU In article <16783553@MVB.SAIC.COM> norman@bellcore.com writes: > [``chunk''] is perhaps > the kind of word (like 'memory' and 'flavor') bound to meet with the > disapproval of Edsger Dijkstra What stronger endorsement could anyone ask for? Wow, one week Preston says that Knuth doesn't write readable webs, and the next week Norman implies that any putative anti-endorsement by Dijkstra is good enough for him! What can we say bad about Tony Hoare, Nicholas Wirth, Alan Kaye, Al Aho or Ken Thompson next week? :-) (apologies to any luminaries I forgot to nominate for abuse :-) I'm no-one to talk, but I tend to agree with Preston. (Knuth is brilliant, but I believe TeX-the-Program and Metafont-the-Program are significant dis-incentives to the spread of literate programming. Virtually anyone I've tried to interest in literate programming who has seen TtP uses it as a counter to my arguments. This may be an argument that TtP is outside the domain of program sizes for which web works well -- maybe hypertext web would be better. I'm not sure the programs Knuth wrote for Jon Bentley's column are completely convincing either -- I think they are perhaps too clever and didactic.) While Dijkstra has many extreme ideas, I think anybody dismisses him at their intellectual peril. My experience is that ideas like literate programming mesh very well with Dijkstra's ideas on program development. (I'm not implying that Norman was dismissing him.) In general I think ritual luminary abuse is probably not very constructive. ../Dave ================================================================================ Archive-Date: Sun, 24 Oct 1993 08:51:18 CST Sender: LP-Mgr@SHSU.edu From: dmason@uwaterloo.ca (Dave Mason) Reply-To: LitProg@SHSU.edu, dmason@UWATERLOO.CA Subject: Luminary abuse (was Re: Inline comments and abstraction) Message-ID: Date: Sun, 24 Oct 1993 04:29:12 GMT To: LitProg@SHSU.EDU In article <16783553@MVB.SAIC.COM> norman@bellcore.com writes: > [``chunk''] is perhaps > the kind of word (like 'memory' and 'flavor') bound to meet with the > disapproval of Edsger Dijkstra What stronger endorsement could anyone ask for? Wow, one week Preston says that Knuth doesn't write readable webs, and the next week Norman implies that any putative anti-endorsement by Dijkstra is good enough for him! What can we say bad about Tony Hoare, Nicholas Wirth, Alan Kaye, Al Aho or Ken Thompson next week? :-) (apologies to any luminaries I forgot to nominate for abuse :-) I'm no-one to talk, but I tend to agree with Preston. (Knuth is brilliant, but I believe TeX-the-Program and Metafont-the-Program are significant dis-incentives to the spread of literate programming. Virtually anyone I've tried to interest in literate programming who has seen TtP uses it as a counter to my arguments. This may be an argument that TtP is outside the domain of program sizes for which web works well -- maybe hypertext web would be better. I'm not sure the programs Knuth wrote for Jon Bentley's column are completely convincing either -- I think they are perhaps too clever and didactic.) While Dijkstra has many extreme ideas, I think anybody dismisses him at their intellectual peril. My experience is that ideas like literate programming mesh very well with Dijkstra's ideas on program development. (I'm not implying that Norman was dismissing him.) In general I think ritual luminary abuse is probably not very constructive. ../Dave ================================================================================ Archive-Date: Sun, 24 Oct 1993 09:01:45 CST Sender: LP-Mgr@SHSU.edu From: dmason@uwaterloo.ca (Dave Mason) Reply-To: LitProg@SHSU.edu, dmason@UWATERLOO.CA Subject: Luminary abuse (was Re: Inline comments and abstraction) Message-ID: Date: Sun, 24 Oct 1993 04:29:12 GMT To: LitProg@SHSU.EDU In article <16783553@MVB.SAIC.COM> norman@bellcore.com writes: > [``chunk''] is perhaps > the kind of word (like 'memory' and 'flavor') bound to meet with the > disapproval of Edsger Dijkstra What stronger endorsement could anyone ask for? Wow, one week Preston says that Knuth doesn't write readable webs, and the next week Norman implies that any putative anti-endorsement by Dijkstra is good enough for him! What can we say bad about Tony Hoare, Nicholas Wirth, Alan Kaye, Al Aho or Ken Thompson next week? :-) (apologies to any luminaries I forgot to nominate for abuse :-) I'm no-one to talk, but I tend to agree with Preston. (Knuth is brilliant, but I believe TeX-the-Program and Metafont-the-Program are significant dis-incentives to the spread of literate programming. Virtually anyone I've tried to interest in literate programming who has seen TtP uses it as a counter to my arguments. This may be an argument that TtP is outside the domain of program sizes for which web works well -- maybe hypertext web would be better. I'm not sure the programs Knuth wrote for Jon Bentley's column are completely convincing either -- I think they are perhaps too clever and didactic.) While Dijkstra has many extreme ideas, I think anybody dismisses him at their intellectual peril. My experience is that ideas like literate programming mesh very well with Dijkstra's ideas on program development. (I'm not implying that Norman was dismissing him.) In general I think ritual luminary abuse is probably not very constructive. ../Dave ================================================================================ Archive-Date: Sun, 24 Oct 1993 11:35:08 CST Sender: LP-Mgr@SHSU.edu From: neeri@iis.ee.ethz.ch (Matthias Neeracher) Reply-To: LitProg@SHSU.edu, neeri@IIS.EE.ETHZ.CH Subject: Re: Luminary abuse (was Re: Inline comments and abstraction) Message-ID: Date: Sun, 24 Oct 1993 12:10:15 GMT To: LitProg@SHSU.EDU dmason@uwaterloo.ca (Dave Mason) writes: >In article <16783553@MVB.SAIC.COM> norman@bellcore.com writes: > > [``chunk''] is perhaps > > the kind of word (like 'memory' and 'flavor') bound to meet with the > > disapproval of Edsger Dijkstra > What stronger endorsement could anyone ask for? >Wow, one week Preston says that Knuth doesn't write readable webs, and >the next week Norman implies that any putative anti-endorsement by >Dijkstra is good enough for him! What can we say bad about Tony >Hoare, Nicholas Wirth, Alan Kaye, Al Aho or Ken Thompson next week? This is a little off-topic, but how about Alan Perlis et al. abusing Tony Hoare? "C.A.R. Hoare has been quoted as saying, ``In many applications, algorithm plays almost no role and certainly presents almost no problems.'' (We wish we could report that he thereupon threw up his hands and abandoned verification, but no such luck.)" -- DeMillo, Lipton, and Perlis, _Social Processes and Proofs of Theorems and Programs_ >I'm no-one to talk, but I tend to agree with Preston. (Knuth is >brilliant, but I believe TeX-the-Program and Metafont-the-Program are >significant dis-incentives to the spread of literate programming. I disagree. While they IMHO might profit from some more global documentation (maybe a diagram of where the various parts fit in), I still believe that they are excellent examples of literate programming. >While Dijkstra has many extreme ideas, I think anybody dismisses him >at their intellectual peril. My problem with Dijkstra is that he pontificates about topics that he appears to have less and less experience with. Does anybody here happen to know when Dijkstra last wrote *himself* a program of any substantial size? I would assume that he has not done so for at least 15 years. Dijkstra is bound to generate resentment with people actually working with computers when he declares that advanced debuggers are unnecessary and harmful, and some system designers actually take him seriously, or when he declares that he does not have time to use word processors and writes everything with a fountain pen (As he did in a CACM article; I don't remember him having made any mention of his Secretary in that article). > My experience is that ideas like >literate programming mesh very well with Dijkstra's ideas on program >development. This is probably true, as literate programming is very well suited to stepwise refinement and having comments typeset is very advantageous if you want to do formal reasoning on the program. >In general I think ritual luminary abuse is probably not very >constructive. I'm not so sure of that. Dijkstra himself seems to have built a considerable part of his reputation on polemics (I mean, who would remember him without "goto statement considered harmful") and has never stopped short of abusing his colleagues (Dijkstras "Selected Writings on Computing: A Personal Perspective" contains a few remarks so nasty that the names of the targets had to be removed out of legal concerns). Matthias ----- Matthias Neeracher neeri@iis.ethz.ch "I came to the conclusion that sex is a sublimation of the work instinct" -- David Lodge, _Small World_ ================================================================================ Archive-Date: Sun, 24 Oct 1993 11:44:51 CST Sender: LP-Mgr@SHSU.edu From: neeri@iis.ee.ethz.ch (Matthias Neeracher) Reply-To: LitProg@SHSU.edu, neeri@IIS.EE.ETHZ.CH Subject: Re: Luminary abuse (was Re: Inline comments and abstraction) Message-ID: Date: Sun, 24 Oct 1993 12:10:15 GMT To: LitProg@SHSU.EDU dmason@uwaterloo.ca (Dave Mason) writes: >In article <16783553@MVB.SAIC.COM> norman@bellcore.com writes: > > [``chunk''] is perhaps > > the kind of word (like 'memory' and 'flavor') bound to meet with the > > disapproval of Edsger Dijkstra > What stronger endorsement could anyone ask for? >Wow, one week Preston says that Knuth doesn't write readable webs, and >the next week Norman implies that any putative anti-endorsement by >Dijkstra is good enough for him! What can we say bad about Tony >Hoare, Nicholas Wirth, Alan Kaye, Al Aho or Ken Thompson next week? This is a little off-topic, but how about Alan Perlis et al. abusing Tony Hoare? "C.A.R. Hoare has been quoted as saying, ``In many applications, algorithm plays almost no role and certainly presents almost no problems.'' (We wish we could report that he thereupon threw up his hands and abandoned verification, but no such luck.)" -- DeMillo, Lipton, and Perlis, _Social Processes and Proofs of Theorems and Programs_ >I'm no-one to talk, but I tend to agree with Preston. (Knuth is >brilliant, but I believe TeX-the-Program and Metafont-the-Program are >significant dis-incentives to the spread of literate programming. I disagree. While they IMHO might profit from some more global documentation (maybe a diagram of where the various parts fit in), I still believe that they are excellent examples of literate programming. >While Dijkstra has many extreme ideas, I think anybody dismisses him >at their intellectual peril. My problem with Dijkstra is that he pontificates about topics that he appears to have less and less experience with. Does anybody here happen to know when Dijkstra last wrote *himself* a program of any substantial size? I would assume that he has not done so for at least 15 years. Dijkstra is bound to generate resentment with people actually working with computers when he declares that advanced debuggers are unnecessary and harmful, and some system designers actually take him seriously, or when he declares that he does not have time to use word processors and writes everything with a fountain pen (As he did in a CACM article; I don't remember him having made any mention of his Secretary in that article). > My experience is that ideas like >literate programming mesh very well with Dijkstra's ideas on program >development. This is probably true, as literate programming is very well suited to stepwise refinement and having comments typeset is very advantageous if you want to do formal reasoning on the program. >In general I think ritual luminary abuse is probably not very >constructive. I'm not so sure of that. Dijkstra himself seems to have built a considerable part of his reputation on polemics (I mean, who would remember him without "goto statement considered harmful") and has never stopped short of abusing his colleagues (Dijkstras "Selected Writings on Computing: A Personal Perspective" contains a few remarks so nasty that the names of the targets had to be removed out of legal concerns). Matthias ----- Matthias Neeracher neeri@iis.ethz.ch "I came to the conclusion that sex is a sublimation of the work instinct" -- David Lodge, _Small World_ ================================================================================ Archive-Date: Mon, 25 Oct 1993 02:20:49 CST Sender: LP-Mgr@SHSU.edu Message-ID: <9310250255.AA11589@mailee.bellcore.com> To: LitProg@SHSU.edu, dmason@UWATERLOO.CA Subject: Re: Luminary abuse (was Re: Inline comments and abstraction) Date: Sun, 24 Oct 93 22:55:57 -0400 From: norman@bellcore.com Reply-To: LitProg@SHSU.edu, norman@BELLCORE.COM > Wow, one week Preston says that Knuth doesn't write readable webs, and > the next week Norman implies that any putative anti-endorsement by > Dijkstra is good enough for him! Actually I have the greatest respect for Dijkstra's work on program correctness and the calculus of guarded commands. I also, however, have the greatest amusement for his handwriting fetish and other eccentricities. Doubtless I will never make a formalist. > What can we say bad about Tony > Hoare, Nicholas Wirth, Alan Kaye, Al Aho or Ken Thompson next week? > :-) (apologies to any luminaries I forgot to nominate for abuse :-) Now wait a minute! Tony Hoare is my hero. > I'm no-one to talk, but I tend to agree with Preston. Me too (all kidding aside). The details of character translation are much less interesting than the line-breaking and other algorithms. > I'm not sure the > programs Knuth wrote for Jon Bentley's column are completely > convincing either -- I think they are perhaps too clever and > didactic.) I find them completely convincing for what they are --- I think MacIlroy used the phrase ``industrial-strength Faberg\'e egg.'' Impressive and repays careful study. I am eagerly looking forward to the upcoming book. > While Dijkstra has many extreme ideas, I think anybody dismisses him > at their intellectual peril. My experience is that ideas like > literate programming mesh very well with Dijkstra's ideas on program > development. (I'm not implying that Norman was dismissing him.) The disappointing thing about those ideas is that a) they haven't been advanced, changed, or enriched in 15 years b) they are tremendously difficult to apply beyond toy examples In my travels I have met one programmer who uses Dijkstra's methods to write serious software---and this is a guy who is brilliant and has made original contributions to program correctness as well as other areas. This is not to say Dijkstra's methods are useless to mere mortals---I use them every time I write a loop---but to say that they have never delivered on their grand promises. > In general I think ritual luminary abuse is probably not very > constructive. But I'm having such fun! OK, so we're far afield from literate programming. I promise to keep my lip buttoned from here on. Norman ================================================================================ Archive-Date: Mon, 25 Oct 1993 02:26:24 CST Sender: LP-Mgr@SHSU.edu From: mpharr@lecter.us.oracle.com (Matt Pharr) Subject: CWEB support for hilit19.el? Message-ID: <1993Oct25.020716.3247@oracle.us.oracle.com> Keywords: CWEB Emacs Hilit19 Frivolity Reply-To: LitProg@SHSU.edu, mpharr@us.oracle.com Date: Mon, 25 Oct 1993 02:07:16 GMT To: LitProg@SHSU.EDU Has anyone figured out a nice set of regexps for CWEB code for Jonathan Stigelman's hilit19.package for GNU Emacs? I've tried to put something together, failed miserably, and wanted to see if someone else has tackled this. (Hilit19 is distributed with Emacs 19 and automatically hilights text in buffers--e.g. for C code, comments are in red text, strings are green, keywords are blue, etc... All this is highly customizable.) -Matt -- Matt Pharr (mpharr@us.oracle.com) | "It's funny how the colors of the real Technical Staff | world only seem real when you see Sun Products Group | them on the screen" Oracle Corporation | -- A Clockwork Orange ================================================================================ Archive-Date: Mon, 25 Oct 1993 02:27:43 CST Sender: LP-Mgr@SHSU.edu Message-ID: <199310250127.AA01806@mucket.vast.unsw.edu.au> To: LitProg@SHSU.edu, dmason@uwaterloo.ca Subject: Re: Luminary abuse (was Re: Inline comments and abstraction) Date: Mon, 25 Oct 1993 11:27:09 +1000 From: Steve Avery Reply-To: LitProg@SHSU.edu, stevea@VAST.UNSW.EDU.AU Dave Mason sez: > Knuth is brilliant, but I believe TeX-the-Program and > Metafont-the-Program are significant dis-incentives to the spread of > literate programming. Sure, but you must admit that the original Web for Pascal was a bit primitive (as probably was the version of Pascal that was used). In all fairness, I think it would be wise to wait for Knuth's next book (the precursor to Volume 4) which apparently has literate programs in it, hopefully using CWEB. cheers -steve p.s. And you can't cite CWEB as an example of Knuth's poor programming, as most of it isn't his (and I don't think its that bad an example of programming either). ================================================================================ Archive-Date: Mon, 25 Oct 1993 03:29:27 CST Sender: LP-Mgr@SHSU.edu From: kasper@iesd.auc.dk (Kasper OEsterbye) Reply-To: LitProg@SHSU.edu, kasper@IESD.AUC.DK Subject: Re: Inline comments and abstraction Message-ID: Date: 25 Oct 93 08:53:41 To: LitProg@SHSU.EDU In this wonderful line of chunks and scraps, I would as a native speaker (of Danish) and a naive speaker (of english) just throw in that I use the word "fragment". I kind of like it because it is exactly what it should be in danish, and seems to work just fine in foreign too. Also it sounds more formal and better suited for papers. -- 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, 25 Oct 1993 03:47:14 CST Sender: LP-Mgr@SHSU.edu Date: Mon, 25 Oct 93 09:42:31 +0100 From: ddw2@sunbim.be (Dominique de Waleffe) Reply-To: LitProg@SHSU.edu, ddw2@SUNBIM.BE Message-ID: <9310250842.AA09017@amadeus.sunbim.be> To: LitProg@SHSU.edu, marcus@X4U2.DESY.DE Subject: nuweb doesnt like Emacs outline-regexp References: >>> "Marcus" == Marcus Speh writes: Marcus> % -*- Mode: outline; outline-regexp: "[@]"; eval: Marcus> (hide-body); -*- The problem is that 'standard' nuweb has no comments of itself. This why I proposed to Preston to include @% as commenting sequence, eating up to the next newline. This is supported by some patches I have for nuweb 0.8 (I have to rebuild them for the current nuweb). Marcus> I would wish nuweb would switch from error to warning Marcus> too. Anybody ever ran into this problem? Is there a simple Marcus> solution? I will be able toi have some time to merge the patches in the current nuweb and am willing to post or the diffs with nuweb 0.87. By the way, you might be interested to look for nuweb.el which work above AucTeX, and mainly (so far) supports editing scraps in their own buffer in another mode. I am currently rewriting this mode in order to also provide navigation across defs and uses of scrap names. This new version will also be able to work without AucTeX. Regards, Dominique ============================================== Dominique de Waleffe ddw@sunbim.be BIM sa Chaussee de Louvain, 510 Tel: +32 2 719 26 14 B-1930 Zaventem Fax: +32 2 725 47 83 Belgium ================================================================================ Archive-Date: Mon, 25 Oct 1993 05:23:36 CST Sender: LP-Mgr@SHSU.edu From: Kevin Mitchell Reply-To: LitProg@SHSU.edu, kevin@DCS.ED.AC.UK Subject: Re: CWeb for the Macintosh Message-ID: Date: Mon, 25 Oct 1993 09:39:37 GMT To: LitProg@SHSU.EDU Subject: CWeb for the Macintosh From: Jerome Chan, yjc@po.cwru.edu Date: Sat, 23 Oct 1993 23:19:27 -0500 In article Jerome Chan, yjc@po.cwru.edu writes: >Where can I find any of these? I've looked into the FAQ list and I don't >see it. :( I've been playing around with a port of cweb for the Mac for a few months now and it seems fairly stable. Once I was convinced of this fact I was going to send the mods to Silvio Levy for inclusion in the cweb distribution. However, if anyone wants to try the port before this happens then they can find the applications in pub/kevin on ftp.dcs.ed.ac.uk Please let me know of any problems you encounter. Here's what I did to get it working on the Mac. First, I needed to allocate a lot of the large arrays dynamically to get around the 32K limit on static arrays. I also had to split common.c into two files, this time to get around the 32K limit on code segment sizes. The interface is a drag and drop one, i.e. you drag the web file over the tangle or weave application (or an alias), and it runs the application on the file. If you select two files (i.e. using shift-click) then it assumes one of them is a change file and uses the file extension to distinguish between them. Errors are written to a log file and you get a pop-up alert if the log file contains any errors at the end of the run. The file types for the .tex and .[ch] files are currently set so that the created files 'belong' to Textures and THINK C respectively. I've created icons for the tangle and weave applications, but I'm no artist and so these are pretty primitive. The main extensions I'd like to do are 1) to avoid overwriting a code file if it hasn't changed (although I'll probably wait a bit to see if this implemented in a later release of cweb) and 2) to try and integrate ctangle into Think C 6.0 as a translator so that it gets called automatically. Enjoy, Kevin. ================================================================================ Archive-Date: Mon, 25 Oct 1993 06:44:32 CST Sender: LP-Mgr@SHSU.edu Date: Mon, 25 Oct 1993 12:41 +0000 (GMT) From: "Eric W. van Ammers, LUW, tel: (+31)8370-83356" Reply-To: LitProg@SHSU.edu, AMMERS@RCL.WAU.NL Subject: Re: Inline comments and abstraction To: LitProg@SHSU.edu Message-ID: <01H4J365MQR48ZJT0V@RCL.WAU.NL> Content-Transfer-Encoding: 7BIT I'm surprised that this discussion about 'chunks' has not referred to serious research that has been done already. For instance Soloway [1,2] finds that programmers tend to think in 'plans' and it looks like these plans are closely related to the refinements we want to document in our literate programs Eric 1. Soloway E., Learning to Program= Learning to Construct Mechanisms and Explanations, CACM 29, 9, 850-858 (1986) 2. Soloway E., Designing Documentaion to Compensate for Delocalized Plans, CACM 31, 11, 1259-1267 (1988) ============================================================================ 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: Mon, 25 Oct 1993 06:57:16 CST Sender: LP-Mgr@SHSU.edu From: schrod@iti.informatik.th-darmstadt.de (Joachim Schrod) Reply-To: LitProg@SHSU.edu, schrod@ITI.INFORMATIK.TH-DARMSTADT.DE Subject: Re: CWeb for the Macintosh Date: 25 Oct 1993 11:17:02 GMT Message-ID: <2agcjeINNn9k@rs18.hrz.th-darmstadt.de> To: LitProg@SHSU.EDU In article , yjc@po.cwru.edu (Jerome Chan) writes: > Where can I find any of these? I've looked into the FAQ list and I don't > see it. :( An update will be in the next FAQ issue. Timothy Murphy did a port of CTANGLE which is available from the Literate Programming Archive: ftp.th-darmstadt.de [130.83.55.75] directory pub/programming/literate-programming/machines/mac/cweb I don't know of a port of CWEAVE. -- Joachim [THD Literate Programming Archive, maintainer] =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= Joachim Schrod Email: schrod@iti.informatik.th-darmstadt.de Computer Science Department Technical University of Darmstadt, Germany ================================================================================ Archive-Date: Mon, 25 Oct 1993 07:10:25 CST Sender: LP-Mgr@SHSU.edu From: schrod@iti.informatik.th-darmstadt.de (Joachim Schrod) Reply-To: LitProg@SHSU.edu, schrod@ITI.INFORMATIK.TH-DARMSTADT.DE Subject: Re: Luminary abuse (was Re: Inline comments and abstraction) Date: 25 Oct 1993 11:33:30 GMT Message-ID: <2agdiaINNn9k@rs18.hrz.th-darmstadt.de> To: LitProg@SHSU.EDU In article , neeri@iis.ee.ethz.ch (Matthias Neeracher) writes: > Dijkstra himself seems to have built a > considerable part of his reputation on polemics (I mean, who would > remember him without "goto statement considered harmful") At least, I would. For his work on structured programming, his work on multi-processing, his work on compiler construction, on the formal definition of programming languages, on the essence of control structures, on non-determinism, and, and, and. In addition, I can't find polemics in his CACM letter. It was a well reasoned statement about the consequences of the (ab)use of certain control structures. Go ahead and read it again! The discussion afterwards was heated and filled with polemics, but not the letter. Yes, he's a very arrogant person and he seems not to be in touch with reality often enough -- but he's brilliant, too. Concerning Literate Programming and Dijkstra: Knuth himself acknowledges the influence of the paradigms of Dijkstra on his ideas of programming style. -- Joachim =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= Joachim Schrod Email: schrod@iti.informatik.th-darmstadt.de Computer Science Department Technical University of Darmstadt, Germany ================================================================================ Archive-Date: Mon, 25 Oct 1993 11:30:52 CST Sender: LP-Mgr@SHSU.edu From: ras@salomon.Princeton.EDU (Robert Shillingsburg) Reply-To: LitProg@SHSU.edu, ras@SALOMON.PRINCETON.EDU Subject: Re: nuweb doesnt like Emacs outline-regexp Message-ID: <1993Oct25.011910.7979@Princeton.EDU> Date: Mon, 25 Oct 1993 01:19:10 GMT To: LitProg@SHSU.EDU marcus@x4u2.desy.de (Marcus Speh) writes: >I have a little problem with nuweb. Since I am working in GNU Emacs, >I'd like to use the outline mode [which all users of web-mode will >appreciate]. Thus, I usually insert a line like >% -*- Mode: outline; outline-regexp: "[@]"; eval: (hide-body); -*- ... >etc. Now, nuweb refuses to follow and aborts with > nuweb: bad @ sequence (file.nu, line 1) The problem, of course, is that nuweb trips over the @ sign in the mode-specifier line. In many cases, you can replace the @ with @@, but in this case, the @ sign is needed by a processor (emacs) which looks at the text before nuweb can change the @@ to a single @. > I would wish nuweb would switch from error to warning too. Anybody >ever ran into this problem? Is there a simple solution? I think a better solution is to use a nuweb comment character (like Preston's proposed @%). Then your mode line will look like: @% -*- Mode: outline; outline-regexp: "[@]"; eval: (hide-body); -*- and nuweb will never see the single @ sign. Now, if we can only convince Preston to implement @%.... :-) Or just hack it up yourself. -Rob -- *********************************************************************** (___) * Rob Shillingsburg Princeton University Computer Science * |===| * ras@cs.princeton.edu This is a *UNIX* system! I know this! * \_/ *********************************************************************** RoboCow ================================================================================ Archive-Date: Mon, 25 Oct 1993 15:02:29 CST Sender: LP-Mgr@SHSU.edu From: mfy@sli.com (Mike Yoder) Reply-To: LitProg@SHSU.edu, mfy@SLI.COM Subject: Re: Luminary abuse (was Re: Inline comments and abstraction) Message-ID: Date: Mon, 25 Oct 1993 16:00:12 GMT To: LitProg@SHSU.EDU Matthias neeracher wrote: >I'm not so sure of that. Dijkstra himself seems to have built a >considerable part of his reputation on polemics (I mean, who would >remember him without "goto statement considered harmful") and has A fact which may be relevant in this context: Dijkstra did not choose this title; it was placed over what had been simply a letter to the editor, as it were, by the publisher. I have read the letter and don't remember its contents as being particularly polemical; perhaps that is because I have seen the claims about the potential harm of gotos borne out both in professional and in academic contexts. Others may disagree, but in my judgment saying that X is harmful isn't polemical when X is, in fact, harmful; nor is it usually polemical even when X isn't harmful. The speaker may, after all, be mistaken. Michael F. Yoder [mfy@sli.com] ================================================================================ Archive-Date: Mon, 25 Oct 1993 15:27:33 CST Sender: LP-Mgr@SHSU.edu From: rfrankel@us.oracle.com (Rick Frankel) Reply-To: LitProg@SHSU.edu, rfrankel@US.ORACLE.COM Subject: Re: nuweb doesnt like Emacs outline-regexp Message-ID: Date: Mon, 25 Oct 1993 19:39:16 GMT To: LitProg@SHSU.EDU Rob write: marcus@x4u2.desy.de (Marcus Speh) writes: >I have a little problem with nuweb. Since I am working in GNU Emacs, >I'd like to use the outline mode [which all users of web-mode will >appreciate]. Thus, I usually insert a line like >% -*- Mode: outline; outline-regexp: "[@]"; eval: (hide-body); -*- ... >etc. Now, nuweb refuses to follow and aborts with > nuweb: bad @ sequence (file.nu, line 1) The problem, of course, is that nuweb trips over the @ sign in the mode-specifier line. In many cases, you can replace the @ with @@, but in this case, the @ sign is needed by a processor (emacs) which looks at the text before nuweb can change the @@ to a single @. How about adding '(("\\.nu" . web-outline-mode)) to auto-mode-alist and then: (defun web-outline-mode () (web-mode) (outline-minor-mode) ;; emacs-19 minor mode. MUCH preferred (make-local-variable outline-regexp) (setq outline-regexp "[@]") (hide-body)) This should automatically do the right thing(TM) any time you edit a .nu file. just a thought... rick -- rfrankel@us.oracle.com richard.frankel@amail.amdahl.com ================================================================================ Archive-Date: Mon, 25 Oct 1993 15:30:49 CST Sender: LP-Mgr@SHSU.edu Date: Mon, 25 Oct 93 12:38:04 EDT From: Lee Wittenberg Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET To: LitProg@shsu.edu, kasper@iesd.auc.dk Subject: Re: Inline comments and abstraction Message-ID: Kasper Osterbye suggests: > In this wonderful line of chunks and scraps, I would as a native speaker > (of Danish) and a naive speaker (of english) just throw in that > I use the word "fragment". I kind of like it because it is exactly what > it should be in danish, and seems to work just fine in foreign too. > Also it sounds more formal and better suited for papers. `Fragment' is certainly acceptable, but I think the final sentence above is an argument ~against~ it. Part of the problem with formal papers is that they use too many 2-bit words. As I keep telling my students: ``People who use long words either don't know what they're talking about, or don't want you to know what they're talking about.'' My vote still goes to `chunk,' the only one-syllable contender. -- Lee leew@pilot.njin.net ================================================================================ Archive-Date: Mon, 25 Oct 1993 15:32:01 CST Sender: LP-Mgr@SHSU.edu Date: Mon, 25 Oct 93 12:32:34 EDT From: Lee Wittenberg Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET To: LitProg@shsu.edu, dmason@uwaterloo.ca Subject: Re: Luminary abuse (was Re: Inline comments and abstraction) Message-ID: Dave Mason writes: > Wow, one week Preston says that Knuth doesn't write readable webs, and > the next week Norman implies that any putative anti-endorsement by > Dijkstra is good enough for him! What can we say bad about Tony > Hoare, Nicholas Wirth, Alan Kaye, Al Aho or Ken Thompson next week? > :-) (apologies to any luminaries I forgot to nominate for abuse :-) I have to admit that I thought about making the same kind of crack about Dijkstra, myself; I'm glad Norman beat me to it :-). Seriously though, Dijkstra does tend to take extreme positions. I like to believe that he does it primarily to start discussion, rather than because he actualy advocates the extremes, but I tend to think the best of people :-). > I'm no-one to talk, but I tend to agree with Preston. (Knuth is > brilliant, but I believe TeX-the-Program and Metafont-the-Program are > significant dis-incentives to the spread of literate programming. > Virtually anyone I've tried to interest in literate programming who > has seen TtP uses it as a counter to my arguments. This may be an > argument that TtP is outside the domain of program sizes for which web > works well -- maybe hypertext web would be better. I'm not sure the > programs Knuth wrote for Jon Bentley's column are completely > convincing either -- I think they are perhaps too clever and > didactic.) I agree with Preston and Dave on this one, but let us not forget that TeX the Program was Knuth's ~first~ literate program. Remember your own early attempts at LP, and look at how far you've come since then. I'm sure that if Knuth were to write TeX now, the exposition and layout would be totally different. Of course, Knuth does have a Turing-like streak that occasionally substitutes cleverness for clarity, but perhaps that is one of the marks of greatness. > In general I think ritual luminary abuse is probably not very > constructive. Agreed, but it is fun. -- Lee leew@pilot.njin.net ``Laugh at the kings, or they'll make you cry.'' -- Stephen Sondheim, "Anyone Can Whistle" ================================================================================ Archive-Date: Mon, 25 Oct 1993 15:37:51 CST Sender: LP-Mgr@SHSU.edu From: mfy@sli.com (Mike Yoder) Reply-To: LitProg@SHSU.edu, mfy@SLI.COM Subject: Re: Inline comments and abstraction Message-ID: Date: Mon, 25 Oct 1993 16:02:32 GMT To: LitProg@SHSU.EDU Let me, as one whose native language is English, loudly endorse Kasper OEsterbyte's use of "fragment." It has the correct meaning in plain, non-technical English, and doesn't collide with existing jargon. Michael F. Yoder [mfy@sli.com] ================================================================================ Archive-Date: Mon, 25 Oct 1993 16:24:45 CST Sender: LP-Mgr@SHSU.edu Date: Mon, 25 Oct 93 17:21:55 -0400 From: koopman@sgi84.ctc.com (Michael G. Koopman) Message-ID: <9310252121.AA00140@sgi84.ctc.com> To: LitProg@SHSU.edu, mfy@SLI.COM CC: LitProg@SHSU.EDU Subject: Fragment Grenadier Reply-To: LitProg@SHSU.edu, koopman@ctc.com Mike Yoder wrote: >Let me, as one whose native language is English, loudly endorse Kasper >OEsterbyte's use of "fragment." It has the correct meaning in plain, >non-technical English, and doesn't collide with existing jargon. There is technical jargon which uses the word `fragment'. Aside from sentence fragment. The word `fragment' is used to describe the pieces scattered about after a shell or other item is fractured, such as by an explosive charge. The weaving and tangling does ``anti-fracture'' the bits of text and code scattered about the web. I still like the taste of `chunklet' better than `fragment,' however. Michael Koopman (mike) Associate Computer Systems Specialist Concurrent Technologies Corporation e-mail: koopman@ctc.com 1450 Scalp Avenue phone: +1-814-269-2637 Johnstown, PA 15904-3321 USA telefax: +1-814-269-2666 ================================================================================ Archive-Date: Mon, 25 Oct 1993 16:33:33 CST Sender: LP-Mgr@SHSU.edu Message-ID: <9310252131.AA22366@mailee.bellcore.com> To: LitProg@SHSU.edu Subject: Results of SURVEY ON PRETTYPRINTING Date: Mon, 25 Oct 93 17:31:20 -0400 From: norman@bellcore.com Reply-To: LitProg@SHSU.edu, norman@BELLCORE.COM Thanks to the 17 respondents to my survey. Here are the results. Recall the scale: > -2 not useful > -1 seldom useful > 0 often useful > +1 useful; can get along without, but only painfully > +2 indispensible > NA I never heard of this, have no opinion In addition, I asked what people preferred among several alternatives. Some people gave preferences; others preferred to rate the alternatives. prettyprinting (PP) rated -0.3 +/- 0.3 (17 ratings) table of contents (TOC) rated +1.4 +/- 0.2 (17 ratings) identifier cross-ref (IX) rated +0.6 +/- 0.2 (16 ratings), 1 NA automatically (AUTOIX) rated +1.0 +/- 0.4 (4 ratings), preferred 8 times by the programmer (USERIX) rated -0.8 +/- 0.5 (4 ratings), preferred 1 time semi-automatic (SEMIIX) rated -0.7 +/- 0.3 (3 ratings), preferred 4 times, OK 3 times, one ``?'' index of identifiers (II) rated +1.3 +/- 0.2 (16 ratings) automatically (AUTOII) rated +1.5 +/- 0.3 (4 ratings), preferred 8 times, one ``?'' by the programmer (USERII) rated -0.3 +/- 0.9 (4 ratings), preferred 1 time semi-automatic (SEMIII) rated -0.7 +/- 0.3 (3 ratings), preferred 3 times, OK 3 times, one ``?'' chunk cross-reference (CX) rated +1.8 +/- 0.1 (17 ratings) chunk index (CI) rated +1.0 +/- 0.2 (17 ratings) chunk numbers (CN) rated +0.7 +/- 0.3 (14 ratings), preferred 1 time numbers for cross-reference page numbers (PAGENO) rated +0.5 +/- 0.3 (6 ratings), preferred 2 times consecutive (CONSEC) rated +0.4 +/- 0.5 (5 ratings), preferred 3 times `1, 2a, 2b, &c' (SUBPAGE) rated +1.3 +/- 0.3 (4 ratings), preferred 8 times Two respondents mentioned that they wanted fully automatic indexing but that the ability to supplement the index manually was important. Here are the ratings in order of importance. I've left out some I took to be preferences. As you can see, differences between nearby features are not significant. Prettyprinting comes out dead last and has the largest margin of difference between it and its neighbors. chunk cross-reference CX rated +1.8 +/- 0.1 (17 ratings) automatic indexing AUTOII rated +1.5 +/- 0.3 (4 ratings) table of contents TOC rated +1.4 +/- 0.2 (17 ratings) index of identifiers II rated +1.3 +/- 0.2 (16 ratings) sub-page numbers SUBPAGE rated +1.3 +/- 0.3 (4 ratings) chunk index CI rated +1.0 +/- 0.2 (17 ratings) chunk numbers CN rated +0.7 +/- 0.3 (14 ratings) identifier cross-ref IX rated +0.6 +/- 0.2 (16 ratings) page numbers PAGENO rated +0.5 +/- 0.3 (6 ratings) consecutive chunk nos CONSEC rated +0.4 +/- 0.5 (5 ratings) prettyprinting PP rated -0.3 +/- 0.3 (17 ratings) Finally, here is the original survey and the coding of responses. Please rate these features: prettyprinting table of contents identifier cross-reference (local, on-page info about local defns & uses) if useful, do you prefer that definitions and uses be identified -- completely automatically -- by the programmer -- programmer marks definitions, uses are identified automatically index of identifiers at end of document if useful, do you prefer that definitions and uses be identified -- completely automatically -- by the programmer -- programmer marks definitions, uses are identified automatically module/chunk cross-reference (automatically generated) module/chunk index (automatically generated) module/chunk numbers (are they important, or do page numbers suffice?) if you use cross-reference or index info, what numbers should be used? -- use page numbers -- use (consecutive) module/chunk numbers -- use module/chunk numbers, but number them by page of appearance (e.g. 1, 2a, 2b, 3, 4a, 4b, 4c) instead of consecutively. Answers: (X means preferred, OK means not preferred but acceptable) (Name of respondent deleted) PP=-1 TOC=+1 IX=+1 AUTOIX=+1 USERIX=-1 SEMIIX=0 II=+1 AUTOII=+1 USERII=-1 SEMIII=0 CX=+1 CI=+1 CN=0 PAGENO=+1 CONSEC=0 SUBPAGE=+1 (Name of respondent deleted) PP=-1 TOC=+2 IX=0 SEMIIX=X II=+2 SEMIII=X CX=+2 CI=+1 CN=0 SUBPAGE=X (Name of respondent deleted) PP=0 TOC=+2 IX=+2 AUTOIX=+2 USERIX=-2 SEMIIX=-1 II=+1 AUTOII=+2 USERII=-2 SEMIII=-1 CX=+2 CI=0 CN=0 PAGENO=0 CONSEC=+1 SUBPAGE=+2 (Name of respondent deleted) PP=0 TOC=+2 IX=+2 AUTOIX=X SEMIIX=OK AUTOII=X SEMIII=OK CX=+2 CI=+2 SUBPAGE=X (Name of respondent deleted) PP=-1 TOC=+1 IX=+2 AUTOIX=+1 USERIX=0 SEMIIX=-1 II=+2 AUTOII=+1 USERII=0 SEMIII=-1 CX=+2 CI=+2 CN=0 PAGENO=0 CONSEC=0 SUBPAGE=+1 (Name of respondent deleted) PP=+2 TOC=+2 IX=+1 AUTOIX=0 USERIX=0 SEMIIX=? II=+2 AUTOII=+2 USERII=+2 SEMIII=? CX=+2 CI=+2 CN=+2 PAGENO=+2 CONSEC=+2 SUBPAGE=X AUTOII=? (Name of respondent deleted) PP=-2 TOC=0 IX=0 AUTOIX=X II=0 AUTOII=X CX=0 CI=0 PAGENO=0 (Name of respondent deleted) PP=-1 TOC=0 IX=0 AUTOIX=X II=+1 AUTOII=X CX=+1 CI=0 CN=X CONSEC=X SUBPAGE=X (Name of respondent deleted) PP=+1 TOC=+1 IX=-1 AUTOIX=X II=+1 AUTOII=X CX=+2 CI=+1 CN=+2 CONSEC=X (Name of respondent deleted) PP=+1 TOC=+2 IX=0 AUTOIX=X SEMIIX=OK II=+1 AUTOII=X SEMIII=OK CX=+2 CI=+2 CN=+2 SUBPAGE=X (Name of respondent deleted) PP=0 TOC=0 IX=+1 AUTOIX=X II=+1 AUTOII=X CX=+2 CI=+1 CN=0 SUBPAGE=X (Name of respondent deleted) PP=+1 TOC=0 IX=NA AUTOIX=X II=+2 AUTOII=X CX=+2 CI=0 CN=+2 CONSEC=X (Name of respondent deleted) PP=+1 TOC=+2 IX=0 SEMIIX=X II=+2 SEMIII=X CX=+2 CI=+2 CN=-2 PAGENO=X (Name of respondent deleted) PP=-1 TOC=+2 IX=0 AUTOIX=X SEMIIX=OK II=+2 AUTOII=X SEMIII=OK CX=+2 CI=+2 CN=+1 SUBPAGE=X (Name of respondent deleted) PP=-1 TOC=2 IX=0 USERIX=X II=2 USERII=X CX=2 CI=0 CN=0 PAGENO=X (Name of respondent deleted) PP=-2 TOC=+2 IX=0 SEMIIX=X II=+2 SEMIII=X CX=+2 CI=+2 CN=+2 SUBPAGE=X (Name of respondent deleted) PP=-1 TOC=+2 IX=+1 SEMIIX=X II=-1 CX=+2 CI=-1 CN=+1 PAGENO=0 CONSEC=-1 SUBPAGE=+1 ================================================================================ Archive-Date: Mon, 25 Oct 1993 17:19:40 CST Sender: LP-Mgr@SHSU.edu Date: Mon, 25 Oct 93 18:16:50 EST From: "Lewis Perin" Reply-To: LitProg@SHSU.edu, perin@med.cornell.edu Message-ID: <65812.perin@cumc.cornell.edu> To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET Subject: Re: Inline comments and abstraction In Message Mon, 25 Oct 93 12:38:04 EDT, Lee Wittenberg writes: >My vote still goes to `chunk,' the only one-syllable contender. My heart still belongs to the saltier `scrap', equally monosyllabic and properly evocative of a piece of paper that can be cut and pasted. (Of course, it also evokes the dog's dinner, but I happen to *like* that association.) ______________________________________________________ __ perin@cumc.cornell.edu (212)746-2946 | |_ \ / : Lew Perin |__ |__ \/\/ : Home: (201)435-2679 ================================================================================ Archive-Date: Mon, 25 Oct 1993 17:57:01 CST Sender: LP-Mgr@SHSU.edu From: sriram@glock.tcs.com (Sriram Srinivasah) Reply-To: LitProg@SHSU.edu, sriram@GLOCK.TCS.COM Subject: Literate programming in Framemaker. Date: 25 Oct 1993 21:31:51 GMT Message-ID: <2ahgk7$dcj@tcsi.tcs.com> To: LitProg@SHSU.EDU I like the concept of LP (or what I understand of it). My understanding is - - Source and documentation is all present in one document - The same document can be compiled, either for execution by a machine, or for publication. - The tools that implement LP provide a framework to achieve the above, and macros to format the stuff effectively. Unfortunately, all the examples that I have seen seem to use Tex as a base. I use FrameMaker for all my documents, and using Tex is simply too much effort devoted to formatting, IMHO. In the current set of tools, one requires a lot of "inband signalling" . That is, one has to have special symbols within the document that tag a certain paragraph as a piece of code, or as a part of the body, etc. The resulting document looks really messy, and it's painful to eyeball the document quickly. I can achieve the same using FrameMaker or most other word processing tools, which allow you to tag paragraph types. So, I can have a paragraph template called "Code", that identifies the Code sections. Now, I can intermix graphics, tables, all kinds of formatting like automatic line numbering, cross-referencing, indexes etc. What I see on the screen is the final output, uncluttered by meta-information. Separating the code from the chaff is very easy, once a Frame file is converted to a MIF file (an awk script is given below) THE $(10^6) question: IS THIS IDEA WORTH EXPLORING FURTHER? I'd dearly like your comments on this subject. I am absolutely new to LP, and haven't read much beyond the FAQ, and some examples. I would think this can be achieved in say, Word for windows etc. which can save to an RTF format. For those with access to framemaker, this is what I propose: 1. Have a paragraph tag called 'Code', and write all your code in this format. 2. Save as a mif file (or use fmbatch). 3. Run this thru the following awk script BEGIN { code = 0 } / # Strip junk in front sub(/^[ ]*$/,"") # Convert smart quotes to standard quotes sub(/\\xd2/,"\"") sub(/\\xd3/,"\"") print next } 4. If you want pieces of code to go to different files, one can always have a special paragraph type ("File") that identifies a specific file type. -Sriram Srinivasan (sriram@tcs.com) ================================================================================ Archive-Date: Mon, 25 Oct 1993 21:20:56 CST Sender: LP-Mgr@SHSU.edu Date: Mon, 25 Oct 1993 19:15:16 -0700 (PDT) From: Charles Bass Reply-To: LitProg@SHSU.edu, chuckb@U.WASHINGTON.EDU Subject: Re: Literate programming in Framemaker. To: LitProg@SHSU.edu, sriram@GLOCK.TCS.COM Message-ID: MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII I think that your idea with framemaker is the only way to go. I looked at a package called ~ winwordweb that was a set of macros for Word for Windows that did what you are doing in Frame. In my opinion this is the nicest way to go because the front end is easy to use WSIWIG etc. The downside is that it is difficult for others to modify your LP program unless the have Frame. The tek based tools are (fairly) portable across unix and dos platforms. At any rate I like your idea of using Frame. chuckb ================================================================================ Archive-Date: Tue, 26 Oct 1993 06:56:25 CST Sender: LP-Mgr@SHSU.edu Date: Tue, 26 Oct 1993 07:52:08 -0400 From: ae1181t@stnfor.ae.ge.com (Osman F Buyukisik) Reply-To: LitProg@SHSU.edu, ae1181t@STNFOR.AE.GE.COM Message-ID: <9310261152.AA06099@stnfor.ae.ge.com> To: LitProg@SHSU.edu, ras@SALOMON.PRINCETON.EDU CC: LitProg@SHSU.EDU Subject: Re: nuweb doesnt like Emacs outline-regexp How about nuweb recognizing the TeX/LaTeX comment delimiter `%'? Then the users do not have learn another command! Osman ================================================================================ Archive-Date: Tue, 26 Oct 1993 07:27:02 CST Sender: LP-Mgr@SHSU.edu From: c21vc@kocrsv01.delcoelect.com (Venkataraman Chandrasekhar) Reply-To: LitProg@SHSU.edu, c21vc@KOCRSV01.DELCOELECT.COM Subject: Some general thoughts on literate programming Message-ID: <1993Oct25.153024.23492@kocrsv01.delcoelect.com> Date: Mon, 25 Oct 1993 15:30:24 GMT To: LitProg@SHSU.EDU In my nineteen years of working as a programmer (a field that I have considered leaving a couple of times because it is not satisfying enough), literate programming is one of the most exciting developments that I have come across. (The only other that even comes close, subjectively speaking of course, is Smalltalk.) I wouldn't have known about it if it weren't for the present newsgroup. Some general thoughts. I had a chance to look at Norman Ramsey's paper (Software-Practice and Experience Vol.21(7),677-683) this weekend. He points out that 'The right model for a literate program is ... not the novel but the car repair manual.' In fact, terms like 'literate', 'publishable', 'books', etc. may cause companies (like ours) to 'run away' from these techniques (in the belief that these are for academia, and other types of companies). Yet, companies like ours can benefit a lot from these techniques. The advantage of these techniques (as I see it in my present state of understanding) is that programs written this way make it possible for a maintenance programmer to take effective action even when his level of familiarity is not high; car repair manual is a good analogy. For me, some of the best written manuals are the manuals that come with HP Laser Jet printers. Their purpose is to enable someone to act effectively (to solve a problem or achieve an intended result for instance, to change the toner cartridge) without going through a lot of preparation/reading/training. The manual makes up for the lack of preparation/reading/training. Techniques for communicating effectively in this way are available and it makes a lot of sense to make use of these in programming. 'literate' and the like have purposes such as 'amusing the reader', produce specific emotional effects,etc. These will be frowned upon as being inappropriate for serious business endeavors. Though, judicious use of these do make the process of using a manual/program quite entertaining and should indeed be welcomed. (The allusion to 'what a tangled web we weave' dawned on me this weekend. I also like the 'copyleft' policy of some GNU utilities.) As for emotional effects, having to make changes to a very badly written program, of course, has moved many to tears. A final thought. B.F.Skinner has a theory of language (stated in Verbal Behavior, 1957). Programming behavior (including that done in a conventional language like English - which is documentation - and that done in a programming language which is of course code) can be profitably analyzed using Skinner's theories; I think that this a rich territory waiting to me mined. (I am aware that many people think of this approach as a 'dead' one - Chomsky etc. After about nineteen years of involvment in this as a hobby, I don't think so). For instance, some project/software methodologies actually make a programmer's job a lot harder/unsatisfactory; behavior analytic explanations shed good light on why this is so. Also, the following may be of some interest to readers of present newsgroup: Skinner has a short paper that helps one enjoy the writing process more and produce better results. (I didn't use it in writing the present posting. I didn't want to go to the extra trouble it takes. I use it usually when I am struggling with a particular piece of writing.) If anyone is interested, please contact me; I will provide the reference. I also appreciate very much this opportunity to exchange ideas with (what I think are) kindred souls. For the record, I also want to say (1) English is a non-native language to me (though I have writing aspirations) (2) apologies to those who feel that this is wasteful of their resources (limited e-mail allowance). Shaker ================================================================================ Archive-Date: Tue, 26 Oct 1993 07:58:23 CST Sender: LP-Mgr@SHSU.edu From: jacojn@inet.uni-c.dk (Jacob Nielsen) Reply-To: LitProg@SHSU.edu, jacojn@INET.UNI-C.DK Subject: Re: nuweb doesnt like Emacs outline-regexp Date: Tue, 26 Oct 1993 14:19:36 GMT Message-ID: To: LitProg@SHSU.EDU Rick (rfrankel@us.oracle.com) writes: [munch] How about adding '(("\\.nu" . web-outline-mode)) to auto-mode-alist and then: (defun web-outline-mode () (web-mode) (outline-minor-mode) ;; emacs-19 minor mode. MUCH preferred (make-local-variable outline-regexp) (setq outline-regexp "[@]") (hide-body)) This should automatically do the right thing(TM) any time you edit a ..nu file. Well, it doesn't work with my Emacs but this does: (defun nuweb-outline-mode () (interactive) ; so I can call it via M-x (nuweb-mode) (setq outline-regexp "@[dDoO]") ; search pattern (outline-minor-mode) ;; emacs-19 minor mode. MUCH preferred (hide-body)) Regards, Jacob -- Jacob Nielsen Email: jacojn@inet.uni-c.dk (my private account) or bc898574@sgi18.bbar.dth.dk (my account at the university) ================================================================================ Archive-Date: Tue, 26 Oct 1993 07:58:32 CST Sender: LP-Mgr@SHSU.edu From: lynbech@daimi.aau.dk (Christian Lynbech) Reply-To: LitProg@SHSU.edu, lynbech@DAIMI.AAU.DK Subject: Literary nomenclature (was: Re: Inline comments and abstraction) Date: 26 Oct 1993 12:28:48 GMT Message-ID: <2aj560$ftc@belfort.daimi.aau.dk> To: LitProg@SHSU.EDU >Let me, as one whose native language is English, loudly endorse Kasper >OEsterbyte's use of "fragment." It has the correct meaning in plain, >non-technical English, and doesn't collide with existing jargon. In fact, the term is used (and probably in more instances than the following). A locally developed OO programming language, the Beta language, uses a `fragment system' as the main vehicle of tying program modules together. An interesting fact is that this fragment system is roughly as powerfull as the tangle part of (say) nuweb, i.e. you define named fragments which are then inserted into `slots'. The system is, as I understand it, derived from grammars (in some appropriate sense), with slots corresponding to non-terminals. Whether this counts against or for `fragment', is a good question. I have untill this thread started used the term `scrap', which I got from spider webs langauge defition files. The process of prettyprinting the code is described as forming bigger scraps from smaller scraps, and though this has nothing to do directly with tangling, it corresponds nicely to my understanding of the tangling process. And since I also find chunk overly informal, I will support the scrap camp. ------------------------------------------------------------------------------ Christian Lynbech | Hit the philistines three times over the | head with the Elisp reference manual. email: lynbech@daimi.aau.dk | - petonic@hal.com (Michael A. Petonic) ------------------------------------------------------------------------------ ================================================================================ Archive-Date: Tue, 26 Oct 1993 08:21:23 CST Sender: LP-Mgr@SHSU.edu From: Thorbjoern Ravn Andersen Reply-To: LitProg@SHSU.edu, ravn@IMADA.OU.DK Message-ID: <199310261318.AA11170@imada.ou.dk> Subject: Re: Some general thoughts on literate programming To: LitProg@SHSU.edu, c21vc@kocrsv01.delcoelect.com Date: Tue, 26 Oct 1993 14:18:53 +0100 (MET) MIME-Version: 1.0 Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: 8bit Venkataraman Chandrasekhar | Also, the following may be of some interest to readers of present | newsgroup: Skinner has a short paper that helps one enjoy the writing | process more and produce better results. (I didn't use it in writing | the present posting. I didn't want to go to the extra trouble it | takes. I use it usually when I am struggling with a particular piece | of writing.) If anyone is interested, please contact me; I | will provide the reference. I am about to write my first larger Lit programme, and I would appreciate reading Skinners paper before starting. I intend to do this as right as I can. I agree with your comment on the LaserJet documentation. I installed a LaserJet 4L yesteday for the first time, and it was a breeze thanks to the excellent manual. I will take heed of your comment regarding using this as inspiration for my own work. So if you would provide references for the Skinner paper, as well as a ftp-location for Norman Ramseys paper I would appreciate it very much. Thanks in advance Regards, -- Thorbjo/rn Andersen ravn@imada.ou.dk ================================================================================ Archive-Date: Tue, 26 Oct 1993 08:40:03 CST Sender: LP-Mgr@SHSU.edu From: johnson@cs.uiuc.edu (Ralph Johnson) Reply-To: LitProg@SHSU.edu, johnson@CS.UIUC.EDU Subject: Re: Literate programming in Framemaker. Message-ID: Date: Tue, 26 Oct 1993 13:08:52 GMT To: LitProg@SHSU.EDU This is basically what the Literate Programmers Workbench from apple.com does. It is a fine idea. -Ralph Johnson ================================================================================ Archive-Date: Tue, 26 Oct 1993 11:37:00 CST Sender: LP-Mgr@SHSU.edu Date: Tue, 26 Oct 93 10:41:54 EDT From: Lee Wittenberg Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET To: LitProg@shsu.edu, sriram@glock.tcs.com Subject: Re: Literate programming in Framemaker. Message-ID: Sriram Srinivasan writes: > > I like the concept of LP (or what I understand of it). > [ stuff omitted ] > I use FrameMaker for all my documents, and using Tex is simply too much effort > devoted to formatting, IMHO. > > In the current set of tools, one requires a lot of "inband signalling" . That is, > one has to have special symbols within the document that tag a certain paragraph > as a piece of code, or as a part of the body, etc. The resulting document looks > really messy, and it's painful to eyeball the document quickly. > > I can achieve the same using FrameMaker or most other word processing tools, which > allow you to tag paragraph types. So, I can have a paragraph template called "Code", > that identifies the Code sections. Now, I can intermix graphics, tables, all kinds > of formatting like automatic line numbering, cross-referencing, indexes etc. > What I see on the screen is the final output, uncluttered by meta-information. > Separating the code from the chaff is very easy, once a Frame file is converted to > a MIF file (an awk script is given below) > > THE $(10^6) question: > IS THIS IDEA WORTH EXPLORING FURTHER? > > I'd dearly like your comments on this subject. I am absolutely new to LP, and > haven't read much beyond the FAQ, and some examples. > > I would think this can be achieved in say, Word for windows etc. which can save > to an RTF format. Actually, what you propose is precisely the way WinWordWEB works, except that it uses internal Word macros instead of saving an RTF file. The idea of a CODE style paragraph that tools can recognize (and tangle and weave, as desired) seems to be the way to go. I recommend you forge on ahead. A lot of people have expressed interest in a Framemaker-based LP tool. -- Lee leew@pilot.njin.net ================================================================================ Archive-Date: Tue, 26 Oct 1993 11:37:24 CST Sender: LP-Mgr@SHSU.edu Date: Tue, 26 Oct 93 12:29:26 -0400 From: koopman@sgi84.ctc.com (Michael G. Koopman) Message-ID: <9310261629.AA04485@sgi84.ctc.com> To: LitProg@SHSU.edu, ravn@IMADA.OU.DK CC: LitProg@SHSU.edu, c21vc@kocrsv01.delcoelect.com Subject: Some general thoughts on literate programming Reply-To: LitProg@SHSU.edu, koopman@ctc.com Thorbjo/rn Andersen wrote regarding Venkataraman Chandrasekhar's article >I agree with your comment on the LaserJet documentation. I installed a >LaserJet 4L yesteday for the first time, and it was a breeze thanks to >the excellent manual. I will take heed of your comment regarding using >this as inspiration for my own work. This document is a User's Manual, not a Technical Manual. I am not criticizing the document or denying it's value to the intended audience. However, I do not believe this document is a good template for a literate program of significant depth. Of course, diagrams and directions for every contingency plausible owing to correct and incorrect use, and use under failure conditions for a complex program would be nice, but seems a daunting task. Much discussion centers around the methods for simplifying the complex program implementation into `User Manual descriptions' with literate techniques. I do not feel such efforts are strictly ``academic'' or infeasible in the ``Real World' of ``Real Programmers.'' The diversity of the User's Manual and the Technical Manual seems relevant to questions concerning literate techniques which support multiple expositions for different audiences. It seems that some readers want a Literate Program to fulfill the User's Manual purpose while others desire a document oriented toward maintenance and enhancement of the code and algorithms. A document (web) which serves both purposes (weave*s*), and contains the implementation (tangle) may be the ideal. >I am about to write my first larger Lit programme, and I would >appreciate reading Skinners paper before starting. Skinner is nothing but a black box to me. Michael Koopman (mike) Associate Computer Systems Specialist Concurrent Technologies Corporation e-mail: koopman@ctc.com 1450 Scalp Avenue phone: +1-814-269-2637 Johnstown, PA 15904-3321 USA telefax: +1-814-269-2666 ================================================================================ Archive-Date: Tue, 26 Oct 1993 12:13:18 CST Sender: LP-Mgr@SHSU.edu Date: Tue, 26 Oct 93 09:33:40 CDT From: preston@cs.rice.edu (Preston Briggs) Reply-To: LitProg@SHSU.edu, preston@CS.RICE.EDU Message-ID: <9310261433.AA02360@cs.rice.edu> To: LitProg@shsu.edu Subject: nuweb doesnt like Emacs outline-regexp I like the hacks to emacs as a way of Preston avoiding work. However, I still plan to add a nuweb comment sequence, say @% meaning ignore through the end-of-line. I don't really like using % by itself. Two reasons: got to be smart to avoid tripping over % in C code, and I like the invariant that every nuweb command begins with an @ sign. In other words, it's all latex until you see an @ character. Preston ================================================================================ Archive-Date: Tue, 26 Oct 1993 12:26:34 CST Sender: LP-Mgr@SHSU.edu Message-ID: <9310261415.AA29702@mailee.bellcore.com> To: LitProg@SHSU.edu, sriram@GLOCK.TCS.COM CC: snd@cs.princeton.edu Subject: Re: Literate programming in Framemaker. Date: Tue, 26 Oct 93 10:15:17 -0400 From: norman@bellcore.com Reply-To: LitProg@SHSU.edu, norman@BELLCORE.COM snd@cs.princeton.edu has done some literate programming using FrameMaker. You might want to ask him about his results. Norman ================================================================================ Archive-Date: Tue, 26 Oct 1993 12:52:23 CST Sender: LP-Mgr@SHSU.edu From: sven@robots.ox.ac.uk (Sven Utcke) Reply-To: LitProg@SHSU.edu, sven@ROBOTS.OX.AC.UK Subject: Re: Literate programming in Framemaker. Message-ID: <1993Oct26.171624.10431@casca.robots.ox.ac.uk> Date: Tue, 26 Oct 1993 17:16:24 GMT To: LitProg@SHSU.EDU In article <2ahgk7$dcj@tcsi.tcs.com> sriram@glock.tcs.com (Sriram Srinivasah) writes: > >I like the concept of LP (or what I understand of it). >My understanding is - > - Source and documentation is all present in one document > - The same document can be compiled, either for execution by a machine, > or for publication. > - The tools that implement LP provide a framework to achieve the above, > and macros to format the stuff effectively. Well, my pet concept is missing: the possibility to write the code in any order I could dream off. >I can achieve the same using FrameMaker or most other word processing tools, which >allow you to tag paragraph types. So, I can have a paragraph template called "Code", >that identifies the Code sections. Now, I can intermix graphics, tables, all kinds >of formatting like automatic line numbering, cross-referencing, indexes etc. >What I see on the screen is the final output, uncluttered by meta-information. >Separating the code from the chaff is very easy, once a Frame file is converted to >a MIF file (an awk script is given below) > >THE $(10^6) question: > IS THIS IDEA WORTH EXPLORING FURTHER? I certainly like the idea. Although I'm unlikely to ever use it myself (I'm hooked on LaTeX and wouldn't even consider using one of nowadays WYSIWYG-formater --- the output is much to ugly), it seems to be a good way to introduce more people to the concept of literate programming. If only the "chunk"-concept would be used (but that can't be so difficult). On the other hand: Isn't that what CLiP is doing? Sven ================================================================================ Archive-Date: Tue, 26 Oct 1993 16:30:44 CST Sender: LP-Mgr@SHSU.edu Date: Tue, 26 Oct 93 17:27:28 EDT From: Lee Wittenberg Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET To: LitProg@shsu.edu Subject: New version of WinWordWEB Message-ID: Stephen McKearney has made a few improvements to the original WinWordWEB, including some support for cross-referencing and an index of chunk names. I've tried it out (minimally) on a copy of WinWord in an office down the hall from mine, and it seems to work. I've made the new, improved version (wordweb2.zip) available for anonymous ftp in the pub/leew directory of bart.kean.edu. The original version is still there, as well. I understand that there are several ftp sites out there that also make copies of WordWEB available. I'd appreciate it if everyone could keep traffic on bart down to a minimum, and wait until these other sites get the new version (assuming that they do). This brings me to the problem of maintenance. WinWordWEB was intended to be an unsupported product, but there seems to be enough interest in it that I feel a moral responsibility to provide some sort of support. However, I do not actually use the product, nor do I have easy access to a copy of Word for Windows. I see 3 alternatives (in order of preference): 1. Someone out there who uses WordWEB volunteers to support it. This would involve fixing the known bugs, and coordinating any modifications and improvements that may be suggested by users. This is really the only way that users can get the support they deserve. 2. Someone out there has contacts with Microsoft who are interested in seeing this project continue, and are willing to provide me with a current copy of WinWord and updates, in return for my supporting the product myself. Perhaps Microsoft might care to include the package with their compiler products? 3. Someone out there has a legal copy of WinWord that they are not using and can send to me, so that I will be able to support WinWordWEB as best I can (at least with the current version of WinWord). Anyone fitting one of the above categories (particularly #1) should contact me directly. Thanks in advance. -- Lee leew@pilot.njin.net ================================================================================ Archive-Date: Wed, 27 Oct 1993 03:44:39 CST Sender: LP-Mgr@SHSU.edu Date: Wed, 27 Oct 93 09:38:56 +0100 From: ddw2@sunbim.be (Dominique de Waleffe) Reply-To: LitProg@SHSU.edu, ddw2@SUNBIM.BE Message-ID: <9310270838.AA18313@amadeus.sunbim.be> To: LitProg@SHSU.edu, ae1181t@STNFOR.AE.GE.COM Subject: Re: nuweb doesnt like Emacs outline-regexp References: <1993Oct25.011910.7979@Princeton.EDU> <9310261152.AA06099@stnfor.ae.ge.com> >>> "Osman" == Osman F Buyukisik writes: Osman> How about nuweb recognizing the TeX/LaTeX comment delimiter Osman> `%'? Then the users do not have learn another command! This would not allow putting some kinds of comments in the body of scraps or make problems with C expresssions like x = y % z; @o f.pro @{ @% -*- prolog -*- % this comment should appear in the source test. @} or would impose treating % differently within or outside scrap bodie. Dominique ================================================================================ Archive-Date: Wed, 27 Oct 1993 06:54:48 CST Sender: LP-Mgr@SHSU.edu Date: Wed, 27 Oct 1993 07:50:04 -0400 From: ae1181t@stnfor.ae.ge.com (Osman F Buyukisik) Reply-To: LitProg@SHSU.edu, ae1181t@STNFOR.AE.GE.COM Message-ID: <9310271150.AA09475@stnfor.ae.ge.com> To: ddw2@sunbim.be CC: LitProg@SHSU.edu Subject: Re: nuweb doesnt like Emacs outline-regexp >>>>> On Wed, 27 Oct 93 09:38:56 +0100, ddw2@sunbim.be (Dominique de Waleffe) said: Dominique> @o f.pro @{ @% -*- prolog -*- Dominique> % this comment should appear in the source Dominique> test. Dominique> @} Dominique> or would impose treating % differently within or outside scrap bodie. I thought there would be no need to have comments in scraps, but may be mistaken. My problem was with web mode emacs I have a limbo.nuweb and it had my email address in a LaTeX comment which nuweb did not like. So I put @@. But also created a diff file to nuweb0.87 that allows % as comment anywhere LaTeX allowed (just doesnt process @ until end of line). Seems to work and not affect the code section. Osman ================================================================================ Archive-Date: Wed, 27 Oct 1993 08:00:01 CST Sender: LP-Mgr@SHSU.edu Date: Wed, 27 Oct 93 13:29:58 +0100 From: ddw2@sunbim.be (Dominique de Waleffe) Reply-To: LitProg@SHSU.edu, ddw2@SUNBIM.BE Message-ID: <9310271229.AA19469@amadeus.sunbim.be> To: ae1181t@stnfor.ae.ge.com (Osman F Buyukisik) CC: preston@cs.rice.edu, litprog@shsu.edu Subject: Re: nuweb doesnt like Emacs outline-regexp References: <9310270838.AA18313@amadeus.sunbim.be> <9310271150.AA09475@stnfor.ae.ge.com> >>> "Osman" == Osman F Buyukisik writes: >>>>>> On Wed, 27 Oct 93 09:38:56 +0100, ddw2@sunbim.be (Dominique >>>>>> de Waleffe) said: Dominique> @o f.pro @{ @% -*- prolog -*- % this comment should Dominique> appear in the source test. @} Dominique> or would impose treating % differently within or Dominique> outside scrap bodie. Osman> I thought there would be no need to have comments in Osman> scraps, but may be mistaken. My problem was with web mode The comment I put in describe the emacs mode in which to edit the scrap. But there's not only comments... I use that in nuweb.el (which has been posted on the list a while back, with a new version coming soon, as well as being mentionned in the next version of the FAQ). Osman> emacs I have a limbo.nuweb and it had my email address in a Osman> LaTeX comment which nuweb did not like. So I put @@. But Osman> also created a diff file to nuweb0.87 that allows % as A long time ago, I did suggest to Preston that @% be included as commenting sequence in nuweb. I belive the best thing is for Preston to include that in nuweb 0.88 as soon as possible, as it looks like eveybody is making up his own commenting patch... For your info, this is a summary of what exists and what's coming up in nuweb.el (I could post the current version, but would rather clean it up first. Those that really wnat to try, just ask by email). Existing: in litprog archives version: ;;; A) Help for editing scraps in language dependent mode ;;; ;;; C-c C-z nuweb-edit-this scrap ;;; Edit the scrap point is on in its own buffer *Source* ;;; put into the mode specified by the buffer local variable ;;; nuweb-source-mode (defaults "emacs-lisp") or into the ;;; mode specified after @{ (on same line) the scrap body as ;;; -*-mode-name-*- ;;; The *Source* buffer is then put into Nuweb minor mode ;;; which adds two bindings: ;;; C-c C-z nuweb-install-this-scrap ;;; Which takes the *Source* buffer contents and puts ;;; it back into the web buffer in place of the old ;;; version of the scrap. ;;; C-c M-k nuweb-kill-this-scrap ;;; Which restores the old scrap, ignoring changes ;;; made. ;;; The original buffer is put in read-only mode until you ;;; call one of the two above functions or kill the ;;; *Source* buffer. ;;; C-@ nuweb-insert-scrap ;;; With no argument: inserts an empty scrap template at ;;; point. ;;; With an argument: prompt for scrap type (oDdD), scrap ;;; name and language mode. A new scrap is inserted and ;;; edited as if nuweb-edit-this-scrap had been called. ;;; ;;; The AucTex action list has a Web entry, that calls nuweb then ;;; latex, and this is the default action for .w files. Only in my current alpha version: ;;; B) Help for navigation on definitions and uses ;;; ;;; C-c C-d r nuweb-compute-d-u ;;; Recompute all defs and uses in current buffer. ;;; C-c C-d p ;;; Pop back to previous def/use ;;; C-c C-d s ;;; Find first definition for scrap name at point ;;; C-c C-d n ;;; Find next definition of same scrap name ;;; C-c C-u s ;;; Find first use of scrap name at point ;;; C-c C-u n ;;; Find next use of smae scrap name ;;; M-mouse3 ;;; Find first def or first use (if on a def -> use, if on a ;;; use -> def) ;;; ;;; Coming RSN: -) The mode in which to edit a scrap defined by @o or @O will be that determined by the filename (using auto-mode-alist) by default, -) The nuweb annotations will be removed from the scrap buffer (they screw up indentation in some modes. -) Also works with standard latex mode Dominique ================================================================================ Archive-Date: Wed, 27 Oct 1993 08:36:52 CST Sender: LP-Mgr@SHSU.edu From: collins@ny.cs.wm.edu (Bob Collins) Reply-To: LitProg@SHSU.edu, collins@NY.CS.WM.EDU Subject: Re: Literate programming in Framemaker. Message-ID: <1993Oct27.122332.22052@cs.wm.edu> Date: Wed, 27 Oct 1993 12:23:32 GMT To: LitProg@SHSU.EDU Sriram Srinivasah recommends using FrameMaker for literate programming. However, Sriram Srinivasah did not mention all the advantages of FrameMaker. FrameMaker is, among other things, a hypertext document generator. One can construct (semi-automatically in FrameMaker 4) a set of hypertext links so that clicking on a hypertext word or picture will display related text. One can have the effect of a table of contents or index without page numbers. One can click on the "title" of a related code fragment to display the code fragment. Consider the primary advantage of a hypertext WYSIWYG document. One is always working with the latest version of the final document. No wasting of printer resources *or* working from slightly outdated printed documents. FrameMaker also has an easy to use book concept with multiple chapters. This is the most logical way to break up a large document. FrameMaker will maintain and regenerate all sorts of links across documents. No need to write obscure macros. No need to modify these macros. FrameMaker allows all sorts of tagging (invisible to the eye but denoted in the bottom margin) of paragraphs and text. Uses of these can be so that lists can be generated and text extracted. This is how one can an automatic cross-reference and make it a hypertext cross-reference. There will no need to use cryptic marks in the text to indicate special things (like the continuation of the body of a code fragment. Use tags and a special typographic standard. Use variables to say "continued." All of these are easily feasible. Sven Utcke objects that he would no longer be able to write code in an arbitrary fashion. Well, he may have misunderstood Sriram Srinivasah who claimed that *with almost no effort* one can use FrameMaker for literate programming. [Indeed, using conditional text for code, within FrameMaker one can view just the code using a simple dialog box. This requires no work at all.] Don't forget that the Knuth system involves running programs to put code fragments together in the correct order. One can also write a program to do a similar thing to MIF output of FrameMaker documents. MIF is Maker Interchange Format, a TeX- or RTF- like marked ASCII text. I have been reading this group for some time. I agree with all those who say the biggest drawback to literate programming is learning a new language -- TeX. TeX, written in the late 70's and popularized in the 80's is very much a 60's product in its interface. Granted it does things that were not done in the 60's. But it sure feels like JCL. Knuth, a wise and witty man, is a hacker at heart. He thinks obscurely and at a low level. He chooses low-level assembly language to describe algorithms. I cannot figure out how he has such a delightful sense of humor and an assembly language mentality. We seem to apotheosize the one person who least practices the things that make literate programming such a nice idea. [Knuth reminds me of a story (apocryphal?) about John von Neumann. At a party von Neumann was asked the puzzle: two trains 100 miles apart are approaching each other at 50 mph. A bumblebee, starting at one train, travels between trains at 25 mph, reversing directions when reaching an aproaching train. How far does the bumblebee travel before being crushed? von Neumann thought a short moment and promptly answered 25 miles. When asked if he knew the trick, he acted puzzled and said that he summed the infinite series.] The *only* advantages of TeX that I know of are that it does mathematical typesetting nicely and it's free. FrameMaker does mathematical typesetting sufficiently well for literate programming. Bob Collins, collins@cs.wm.edu CS Dept, Coll of Wm & Mary (est 1693) ================================================================================ Archive-Date: Wed, 27 Oct 1993 09:11:42 CST Sender: LP-Mgr@SHSU.edu From: sriram@glock.tcs.com (Sriram Srinivasah) Reply-To: LitProg@SHSU.edu, sriram@GLOCK.TCS.COM Subject: Re: Literate programming in Framemaker. Date: 27 Oct 1993 13:45:26 GMT Message-ID: <2alu1m$n0n@tcsi.tcs.com> To: LitProg@SHSU.EDU In article <1993Oct27.122332.22052@cs.wm.edu>, collins@ny.cs.wm.edu (Bob Collins ) writes: > Sriram Srinivasah recommends using FrameMaker for literate programming. > However, Sriram Srinivasah did not mention all the advantages of FrameMaker. > FrameMaker is, among other things, a hypertext document generator. One > can construct (semi-automatically in FrameMaker 4) a set of hypertext > links so that clicking on a hypertext word or picture will display > related text. One can have the effect of a table of contents or index > without page numbers. One can click on the "title" of a related code > fragment to display the code fragment. > > [ FrameMaker plug deleted ....] > > I have been reading this group for some time. I agree with all those > who say the biggest drawback to literate programming is learning a new > language -- TeX. TeX, written in the late 70's and popularized in the > 80's is very much a 60's product in its interface. > You can say this again! Now, for the downside of using Frame, or any other word processor. Note that I'm definitely NOT in favor of Tex still .. o Speed of development - I am a power Emacs/Vi user, and Frame or WFW simply doesn't cut it in terms of development speed. o All my text processing tools can't be used - egrep, class browsers, awk, sed, sdiff, tags, and a zillion others. I managed to fix my mifToCode script to generate the correct line numbers, so that GDB isn't confused - but you see the point - I now have to worry about issues that weren't in text-land. o SCCS isn't very happy either. Have to move my stuff over to RCS, to be able to check in or out stuff. Either that, or have to convert all files to MIF before using SCCS. o Integrating this with other code in a production development environment seems to be a pain (I tried). (Other code - stuff already developed). o Using Tex and remaining in text-mode is a concept I find very painful. I do not want to think formatting when I am into development. Bob Collins has already said all I would have wanted to. I guess I need a powerful argument for undergoing these hassles, especially the development cycle speed, before I really change my ways. Practically, how does it payback? Does it result in fewer edit/compile/run cycles? Has anyone used it for projects that have, say, 2 million lines of code, and has to be pushed out, say, yesterday? (Someone other than Knuth, that is!) Meanwhile, I convinced one of my friends to use my scripts and paragraph formats for a book he's working on. At the very least, we can test out the code that is going into the book by extracting all of it and compiling it. He's not completely in favor of doing development inside Frame yet. Sriram Srinivasan. -- Note: my name is misspelt by the mailer. (sriram@tcs.com) ================================================================================ Archive-Date: Wed, 27 Oct 1993 10:04:39 CST Sender: LP-Mgr@SHSU.edu From: c21vc@kocrsv01.delcoelect.com (Venkataraman Chandrasekhar) Reply-To: LitProg@SHSU.edu, c21vc@KOCRSV01.DELCOELECT.COM Subject: Reference to Skinner's article on writing Message-ID: <1993Oct26.190439.12488@kocrsv01.delcoelect.com> Date: Tue, 26 Oct 1993 19:04:39 GMT To: LitProg@SHSU.EDU I am having trouble locating my copy at home. Of the top of my head here are the details: A Thinking Aid, B.F.Skinner, Journal of Applied Behavior Analysis, after 1985 for sure. I will look for the actual issue at Purdue University this weekend. (This is where I got Norman Ramsey's article.) I will post again when I have more specific details. Thanks for your interest. Shaker ================================================================================ Archive-Date: Wed, 27 Oct 1993 10:04:44 CST Sender: LP-Mgr@SHSU.edu From: c21vc@kocrsv01.delcoelect.com (Venkataraman Chandrasekhar) Reply-To: LitProg@SHSU.edu, c21vc@KOCRSV01.DELCOELECT.COM Subject: Effective instructions for maintenance programmers Message-ID: <1993Oct26.210137.17211@kocrsv01.delcoelect.com> Date: Tue, 26 Oct 1993 21:01:37 GMT To: LitProg@SHSU.EDU The subject is HP Users's Manual as an example of something that provides good instructions to its intended readers so that they can act effectively in solving their problems >This document is a User's Manual, not a Technical Manual. I am not >criticizing the document or denying it's value to the intended >audience. However, I do not believe this document is a good template >for a literate program of significant depth. Of course, diagrams and >directions for every contingency plausible owing to correct and >incorrect use, and use under failure conditions for a complex program >would be nice, but seems a daunting task. Much discussion centers >around the methods for simplifying the complex program implementation >into `User Manual descriptions' with literate techniques. I do not >feel such efforts are strictly ``academic'' or infeasible in the >``Real World' of ``Real Programmers.'' > >The diversity of the User's Manual and the Technical Manual seems >relevant to questions concerning literate techniques which support >multiple expositions for different audiences. It seems that some >readers want a Literate Program to fulfill the User's Manual purpose >while others desire a document oriented toward maintenance and >enhancement of the code and algorithms. A document (web) which serves >both purposes (weave*s*), and contains the implementation (tangle) may >be the ideal. Some responses to Michael Koopman's recent posting quoted above: I did not intend to imply that the HP User's Manual is a 'good template for a literate program ...' nor did I have 'diagrams and directions for every contingency ... ' in mind. What I was thinking was these: the HP User's Manual does a terrific job in helping its intended audience do user type functions - changing toner cartridges, loading different fonts,etc. Information is organized in an easy to find way. The whole experience is generally pleasing. Not a lot of prior experience is required. Not a lot of 'look under another topic' type of stuff is required. The whole thing is geared to the reader taking effective action. I can imagine a programmer's manual doing a similarly terrific job in helping its intended audience do maintenance programmer type of functions. To give an example (based on a recent experience): in some system, the requirement is to do one type of checksum if the year invloved is 94 and do another type of checksum if the year invloved is > 94. An existing program had code calculating checksums for 94 and 95. For 96 etc., it did nothing. This error had to be fixed. The maintenance programmer function involved here is to change a test such that for any year >94, the previous 95 logic is executed. I can imagine a good version of this system which provides most (if not all) of the advantages I have listed above for the HP User's Manual. Namely, what is done for the various years (for checksumming) should be very easy to locate by someone with no experience with the system (for instance, someone with 'college level curiosity'). In other words, a new maintenance programmer should be able to realize pretty easily from the program that nothing is done for the years >95. It should also be easy to realize that the requirement for years >95 is the same as that for 95. (In fact, if the original programmer had organized her program/document this well, she would have realized that she is not providing any checksumming function for >95.) In sum, if the program/document makes it very easy for someone new to make this change and do it without getting irritated (just like using the HP User's Manual one can change toner cartridges without much irritation; without such a nice manual, a few cusswords and kicking of the printer are highly likely), it has met the criterion of aiding/enhancing effective action by a new reader/user. Outside of such maintenance programmer's manual, of course, enduser(nonprogrammer) manuals are needed for people to type in commands to perform checksum on actual parts etc. Instructions for these readers may/may not belong in a literate program. (Of course, these manuals can be written providing the above benefits, etc.) Also, judicious decisions should be made (based on intended audience and several other factors) in areas like how much spoonfeeding to make etc. If a lot users are likely to be so angry that they cannot even see the print on a book when they are likely to use the book (as when going to the printer manual when their printer suddenly stops working), perhaps all the possible 'spoonfeeding' (i.e., diagrams and directions for every contingency plausible owing to correct and incorrect use, and use under failure conditions, etc.) should be considered. I certainly do not expect the program/document for the above case to tell me, for instance, 'if year = 96, add code to handle this'. If the program/document guides me quickly to go the section invloved, no other info is needed (other than what the reqmt for years >95 is). If the instructions quickly take me to a certain depth and if I am assured that the instructions are accurate, asking a maintenance programmer to dig through the next several levels is not unreasonable. Having to reinvent the wheel evey single time is what I want to avoid. Also, in my view, maintenance programmers needs are less important than endusers needs, if there is a contention for resources. However, most of the times both constituencies can be served well without one having to sacrifice for the other; what is in short supply is the knowhow/desire to do it. I hope that these type of postings are of some value. If you guys start complaining, I will have to take my thoughts to alt.professional.wrestling. Also, my friend Ron Peithman told me yesterday that the following is the full quote: 'What a tangled web we weave, when we pratice to deceive'. Some project manager types that I know are indeed literate programmers without realizing that they are: they do weave tangled webs; practice quite a bit of deception. Shaker ================================================================================ Archive-Date: Wed, 27 Oct 1993 10:36:07 CST Sender: LP-Mgr@SHSU.edu From: cgra@btma74.nohost.nodomain (Chris Gray) Subject: Re: Inline comments and abstraction Message-ID: <2177@se.alcbel.be> Date: 27 Oct 93 14:26:43 GMT Reply-To: LitProg@SHSU.edu, cgra@se.alcbel.be To: LitProg@SHSU.EDU In article <2abjai$965@TAMUTS.TAMU.EDU>, bdubbs@cs.tamu.edu (Bruce Dubbs) writes: In article <16782125@mvb.saic.com>, Lee Wittenberg wrote: >The problem with `chunk' is that it does have this use in Psychology. >The more complete term is `cognitive chunk'. I have proposed the term >`cognitve block' in a paper now being refereed. Ooerr. In that context `cognitive block' makes me think of `mental block' or `writer's block'. _________________________________________________________________________ Chris Gray cgra@se.alcbel.be Compu$erve: 100065.2102 ================================================================================ Archive-Date: Wed, 27 Oct 1993 11:19:17 CST Sender: LP-Mgr@SHSU.edu From: schrod@iti.informatik.th-darmstadt.de (Joachim Schrod) Reply-To: LitProg@SHSU.edu, schrod@ITI.INFORMATIK.TH-DARMSTADT.DE Subject: Contents of the Literate Programming Archive Date: 27 Oct 1993 15:57:49 GMT Message-ID: <2am5ptINN11vp@rs18.hrz.th-darmstadt.de> To: LitProg@SHSU.EDU Finally, I've found the time to write an overview of the contents of the LitProg Archive. I thought it might be of interest for the readers of this newsgroup. (Of course, this file itself is available from the LPA: ftp.th-darmstadt.de:pub/programming/literate-programming/Contents.) Still to add: webmerge, scanweb, the WEB Mac port of Kevin Mitchell (when it's got released eventually). Enjoy, Joachim ---------------- included file follows: # literate-programming/Contents 27 Oct 93 -*- Indented-Text -*- #------------------------------------------------------------ The material available from the Literate Programming Archive is categorized, each category is put in a directory tree. While this structure (which is described in the README files) supports browsing, the need for quick access to a specific Literate Programming tool remains. This file shall assist you in this need. It presents the *WEB systems and tools available, in an alphabetic order, and names the directory where you can find it. In addition to the systems mentioned below, the LitProg Archive features texts in the directory Documentation: FAQs, papers, and an extensive bibliography in BibTeX format. Since this file is updated manually, I cannot guarantee that it's up to date. Send reports about inconsistency 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 -- for DOS machines/ms-dos -- for VMS machines/vms cnoweb c.c++ CWEB (Levy/Knuth) C++, ANSI C, K&R C -- source c.c++ -- DOS port machines/ms-dos -- Mac port machines/mac/cweb only CTANGLE cweb style c.c++ CWEB programs as LaTeX documents CWEB (Schrod) not supported any more send me mail if you have historic interests :-) Funnelweb independent FWEB multi-lingual WEB -- source fweb -- DOS port machines/ms-dos Knit pascal not supported any more lit2x independent [????] from Glasgow LPW machines/mac CAVEAT: Shareware! MapleWEB maple [SpiderWEB?] MWEB (Schrod/Detig) modula-2 not supported any more MWEB (Sewell) modula-2 not supported any more noweb independent uses the UNIX toolbox paradigm nuweb independent ProTex independent [really a LitProg system?] RWEB reduce [SpiderWEB?] SpiderWEB WEB generator, in awk -- source spiderweb -- DOS port machines/ms-dos -- OS/2 port machines/os2 -- Mac port machines/mac TIE Tools Change File Merger WEB The basis, it started with it... -- source pascal -- DOS port machines/ms-dos WEB mode Tools for GNU Emacs Systems without support of refinements -------------------------------------- MAKEPROG independent is here for my own convenience :-) SchemeWEB lisp -- =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= Joachim Schrod Email: schrod@iti.informatik.th-darmstadt.de Computer Science Department Technical University of Darmstadt, Germany [THD Literate Programming Archive, maintainer] ================================================================================ Archive-Date: Wed, 27 Oct 1993 11:45:30 CST Sender: LP-Mgr@SHSU.edu From: cgra@btma74.nohost.nodomain (Chris Gray) Subject: Re: Luminary abuse (was Re: Inline comments and abstraction) Message-ID: <2178@se.alcbel.be> Date: 27 Oct 93 15:23:00 GMT Reply-To: LitProg@SHSU.edu, cgra@se.alcbel.be To: LitProg@SHSU.EDU In article , neeri@iis.ee.ethz.ch (Matthias Neeracher) writes: >[...] >Dijkstra is bound to generate resentment with people actually working >with computers when he declares that advanced debuggers are unnecessary >and harmful, and some system designers actually take him seriously, Hear hear hear hear hear. The system on which I have spent half of my working life started out with that kind of thinking---no need for online debugging, everything will be ``finite message machines'' individually tested beforehand,... several years later, the debugging stuff was all there, but not until the project had soaked up enough unbudgeted man- power to bring one of the world's great multinationals to its knees. Disclaimer: any resemblance to actual great multinationals, whether living or dead, is entirely coincidental. __________________________________________________________________________ Chris Gray cgra@se.alcbel.be Compu$erve: 100065.2102 ================================================================================ Archive-Date: Wed, 27 Oct 1993 13:52:07 CST Sender: LP-Mgr@SHSU.edu From: dmason@uwaterloo.ca (Dave Mason) Reply-To: LitProg@SHSU.edu, dmason@UWATERLOO.CA Subject: Re: Reference to Skinner's article on writing Message-ID: Date: Wed, 27 Oct 1993 17:41:10 GMT To: LitProg@SHSU.EDU In article <1993Oct26.190439.12488@kocrsv01.delcoelect.com> c21vc@kocrsv01.delcoelect.com (Venkataraman Chandrasekhar) writes: > I am having trouble locating my copy at home. > Of the top of my head here are the details: > > A Thinking Aid, B.F.Skinner, Journal of Applied Behavior Analysis, after 1985 for > sure. 1987. v20, pp189-190 A very brief article describing essentially a physical manifestation of an outline editor. Several useful comments as well. I certainly concur that outline editors are *very* useful for writing papers. ../Dave ================================================================================ Archive-Date: Wed, 27 Oct 1993 18:17:48 CST Sender: LP-Mgr@SHSU.edu From: philipr@extro.ucc.su.OZ.AU (Philip Rhoades) Reply-To: LitProg@SHSU.edu, philipr@EXTRO.UCC.SU.OZ.AU Subject: Re: New version of WinWordWEB Message-ID: Date: Wed, 27 Oct 1993 22:37:15 GMT To: LitProg@SHSU.EDU Lee Wittenberg writes: >Stephen McKearney has made a few improvements to the original >WinWordWEB, including some support for cross-referencing and an index >of chunk names. I've tried it out (minimally) on a copy of WinWord in >an office down the hall from mine, and it seems to work. I've made >the new, improved version (wordweb2.zip) available for anonymous ftp >in the pub/leew directory of bart.kean.edu. The original version is >still there, as well. I understand that there are several ftp sites >out there that also make copies of WordWEB available. I'd appreciate >it if everyone could keep traffic on bart down to a minimum, and wait >until these other sites get the new version (assuming that they do). What is WinWordWEB actually for? Integrating WfW with WWW? -- Philip Rhoades * First Year Biology * University of Sydney phil@biox.bio.su.OZ.AU (best) or philipr@extro.ucc.su.OZ.AU Phone: +61 2 692 2765 * Fax: +61 2 692 2175 ================================================================================ Archive-Date: Thu, 28 Oct 1993 04:00:19 CST Sender: LP-Mgr@SHSU.edu To: litprog@shsu.edu From: mckearney_s Reply-To: LitProg@SHSU.edu, mckearney_s@BT-WEB.BT.CO.UK Subject: Re: New version of WinWordWEB Date: Thu, 28 Oct 1993 08:57:40 +0000 Hello, I use WinWordWeb and have continued to make minor changes to it. I would be willing to try to support and co-ordinate it. The main constraint would be that it does not become such a large task as to require a lot of time. Lee, thanks for distributing the version of WinWordWeb I changed. The problem I had in distributing to people who requested it (through ftp) has been solved, I think. Can it be placed in the LitProg archive? If no one else offers their services I will try to support it. Stephen Mc Kearney ================================================================================ Archive-Date: Thu, 28 Oct 1993 05:38:56 CST Sender: LP-Mgr@SHSU.edu From: shf@netcom.com (Stuart Ferguson) Reply-To: LitProg@SHSU.edu, shf@NETCOM.COM Subject: Re: Reference to Skinner's article on writing Message-ID: Date: Thu, 28 Oct 1993 05:49:08 GMT To: LitProg@SHSU.EDU +-- dmason@uwaterloo.ca (Dave Mason) writes: | I certainly concur that outline editors are *very* useful for writing | papers. Yes they are. This leads me to ask about an idea that's been troubling me for a few weeks. Is there any interest in, or tools for, treating the text portion of a literate program as a web? This would let one write prose in the top-down, structured manner of an outline editor. For the most part I can live with moving blocks of text around in an editor for this, except for one thing. I would like to be able to generate a *set* of documents from one literate program. The program itself, a client interface reference, a user primer, change log, etc. I can do this to some extent by selectivly including only certain portions of the main text into each document, but I cannot reorder text selections to put them in the most logical order in each document. And you know, if any programming language needs to be more literate, it's TeX. - "Meta-man" Ferguson -- Stuart Ferguson (shf@netcom.com) "Oh Dear Lord -- the canary exploded!" ================================================================================ Archive-Date: Thu, 28 Oct 1993 06:37:53 CST Sender: LP-Mgr@SHSU.edu Date: Thu, 28 Oct 93 7:35:55 EDT From: Lee Wittenberg Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET To: LitProg@shsu.edu, mckearney_s@bt-web.bt.co.uk Subject: Re: New version of WinWordWEB Message-ID: Stephen: > I use WinWordWeb and have continued to make minor changes to it. I would > be willing to try to support and co-ordinate it. The main constraint > would be that it does not become such a large task as to require a lot > of time. Lee, thanks for distributing the version of WinWordWeb I > changed. The problem I had in distributing to people who requested > it (through ftp) has been solved, I think. Can it be placed in the > LitProg archive? If no one else offers their services I will try to > support it. I don't know about the LitProg archive. I assume that it will end up there eventually, anyway. I just don't have the time to follow up on all these things myself. If no one else offers their services, as you say, I'll let you know, and you can take over. Thanks for the offer. -- Lee ================================================================================ Archive-Date: Thu, 28 Oct 1993 06:43:02 CST Sender: LP-Mgr@SHSU.edu Date: Thu, 28 Oct 93 7:41:02 EDT From: Lee Wittenberg Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET To: LitProg@shsu.edu, philipr@extro.ucc.su.oz.au Subject: Re: New version of WinWordWEB Message-ID: Philip Roades asks: > What is WinWordWEB actually for? Integrating WfW with WWW? WinWordWEB is a collection of macros that provide a simple literate programming environment. It provides a ``code'' paragraph style for inserting chunks [sic] of code into documents, and macros for naming code chunks, and ``tangling'' them into a compilable program. If you're a WfW user and interested in LP (which is practically a given, if you read the newgroup/maillist), please grab yourself a copy and play around with it. -- Lee leew@pilot.njin.net ================================================================================ Archive-Date: Thu, 28 Oct 1993 09:53:05 CST Sender: LP-Mgr@SHSU.edu From: schrod@iti.informatik.th-darmstadt.de (Joachim Schrod) Reply-To: LitProg@SHSU.edu, schrod@ITI.INFORMATIK.TH-DARMSTADT.DE Subject: Re: Literate programming in Framemaker. Date: 28 Oct 1993 14:28:17 GMT Message-ID: <2aoku1INNr3k@rs18.hrz.th-darmstadt.de> To: LitProg@SHSU.EDU In article <1993Oct27.122332.22052@cs.wm.edu>, collins@ny.cs.wm.edu (Bob Collins) writes: > Knuth, > a wise and witty man, is a hacker at heart. He thinks obscurely and at > a low level. He chooses low-level assembly language to describe algorithms. > I cannot figure out how he has such a delightful sense of humor and > an assembly language mentality. How? Simple: he's a scientist. How do you do *exact* analysis of run-time behaviour without an exact notion of the cost of basic operations? Give me the answer, and then we can see if we can get rid of MIX. Btw, Vol. 4 won't have MIX any more. > The *only* advantages of TeX that I know of are that it does mathematical > typesetting nicely and it's free. FrameMaker does mathematical typesetting > sufficiently well for literate programming. How do you edit your FrameMaker documents on more than 40 different operating systems, ranging from 8086 PCs to Crays? How do you use FrameMaker in a convenient way as a background system? How do you use many languages? (Remember: Not everyone writes in English...) Don't get me wrong: FrameMaker is surely one of the better commercial systems around -- but your evalution of the differences between TeX and FrameMaker is not even. -- Joachim =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= Joachim Schrod Email: schrod@iti.informatik.th-darmstadt.de Computer Science Department Technical University of Darmstadt, Germany ================================================================================ Archive-Date: Thu, 28 Oct 1993 11:17:26 CST Sender: LP-Mgr@SHSU.edu Message-ID: <9310281609.AA16373@mis.sequoia.com> Subject: Re: Literate programming in Framemaker. To: LitProg@SHSU.edu, schrod@ITI.INFORMATIK.TH-DARMSTADT.DE Date: Thu, 28 Oct 93 12:09:36 EDT X-MX-Warning: Warning -- Invalid "From" header. From: Mark R. Friedman Reply-To: LitProg@SHSU.edu, markf@SEQUOIA.SEQUOIA.COM From Joachim's response to Bob Collins' comments on Framemaker's strengths: > > > The *only* advantages of TeX that I know of are that it does mathematical > > typesetting nicely and it's free. FrameMaker does mathematical typesetting > > sufficiently well for literate programming. > > How do you edit your FrameMaker documents on more than 40 different > operating systems, ranging from 8086 PCs to Crays? > How do you use FrameMaker in a convenient way as a background system? > How do you use many languages? (Remember: Not everyone writes in > English...) > I'll add 2 even ``lower-end'' systems to the editing list --- I often take notes & revise drafts on an _ancient_ Tandy T102 (not even MS-DOS, but it can spit out ascii), and I have 3 daughters (ages 11 to 18) that ``share'' an 80286 to (La)TeX documents created on a trio of (also ancient) Apple ]['s. The point, of course is quite simple --- if it can produce ascii outout, _anything_ can be used for entry & editing. As for the oft cited difficulty of learning LaTeX, my daughters have done _all_ their school reports since 3rd grade as well as lots of other ``documents'' (my 15 year old produces Girl Scout troop meeting minutes, plans & budgets), in English, French, German, Spanish and even ASL (American Sign Language --- a one-off report using a wonderful `hands' Metafont file). Overkill? Absolutely, but they happen to love it (they're even more critical of sloppy or ugly documents that I am, and I thought I was the perfectionist in the family). It has also led to various amusing incidents, like when my oldest was in 7th grade her English teacher stated that there was ``only one right way to format a bibliograpy''. Allyson's response was to take my copy of the Chicago Manual of Style to school, along with about a dozen versions of her assignment's bibliography, all formatted by different .bst styles, and ask which one was the ``right'' one... -- |---------------------------------------------------------------| | Mark R. Friedman | | | markf@sequoia.com | | |---------------------------------------------------------------| ================================================================================ Archive-Date: Thu, 28 Oct 1993 16:56:40 CST Sender: LP-Mgr@SHSU.edu Date: Thu, 28 Oct 93 17:54:04 -0400 From: norman@bellcore.com (Norman Ramsey) Reply-To: LitProg@SHSU.edu, norman@BELLCORE.COM Message-ID: <9310282154.AA05601@flaubert.bellcore.com> To: litprog@shsu.edu Subject: Announcing a new version of noweb (In case you didn't know, noweb is a language-independent literate-programming tool whose watchwords are simplicity and extensibility. If you're not already familiar with noweb, the full README file will follow in a separate message. It has complete information about noweb, including how to get sources by anonymous ftp. If you know something about noweb, read on.) I am very pleased to be able to announce a major new release of noweb. The major change visible to users is support for local identifier cross-reference and an index of identifiers. Those of us who write Icon, TeX, or yacc code can enjoy the dubious benefits of automatic discovery of definitions and uses; others will have to fall back on a scheme by which definitions are marked manually and uses are discovered automatically. There are serious changers under the hood which should be of profound interest to the small cadre of noweb hackers out there. A -filter option in the notangle and noweave scripts makes it easy to attach tools that manipulate noweb information in language-dependent or other customized ways. For example, the automatic indexing codes for Icon, TeX, and yacc are about 30 lines each. I hope that one of you will write a tool that automatically recognizes definitions of interesting identifiers in C or C++ programs. The same hooks have been used in two different contributed prettyprinters. Finally, the LaTeX support is drastically revised, and you have far too many options and hooks to use in fiddling with the output. Many of these revisions are in response to complaints by users that they wanted things formatted differently. Major thanks are due to Preston Briggs and Dave Love, without whom there wouldn't be a noweb 2.5. Thanks also to Lee Wittenberg for finding innumerable bugs and to George Greenwade for helping set up the distribution. Norman Ramsey norman@bellcore.com ================================================================================ Archive-Date: Thu, 28 Oct 1993 16:56:53 CST Sender: LP-Mgr@SHSU.edu Date: Thu, 28 Oct 93 17:54:20 -0400 From: norman@bellcore.com (Norman Ramsey) Reply-To: LitProg@SHSU.edu, norman@BELLCORE.COM Message-ID: <9310282154.AA05605@flaubert.bellcore.com> To: litprog@shsu.edu Subject: noweb README file This is version 2.5 of ``noweb'', a low-tech literate programming tool. noweb is available via anonymous ftp from the Comprehensive TeX Archive Network, in directory web/noweb. CTAN includes hosts ftp.shsu.edu, ftp.tex.ac.uk, and ftp.uni-stuttgart.de. These sites mirror the master directory bellcore.com:pub/norman/noweb. You can also get the master shar file bellcore.com:pub/norman/noweb.shar.Z. The file INSTALL tells how to build noweb. Changes to this version are so extensive that they are detailed in a separate CHANGES file. They include: -- major enhancements of latex support & INCOMPATIBLE changes to noweave -- language-independent support for an index of identifiers and for local identifier cross-reference. -- a `noweb' command that ``extracts everything.'' -- contributed prettyprinters for Icon, Object-Oriented Turing, and a variant of Dijkstra's language of guarded commands. -- restructured shell scripts to make things easier for hackers (especially -filter). -- bug fixes. INTRODUCTION 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. 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 that code is not prettyprinted. noweb provides extensibility by using the Unix toolkit philosophy. The ``noweb,'' ``notangle,'' and ``noweave'' commands are built from pieces, which are then assembled in pipelines using shell scripts. The pieces include: markup convert noweb file from human syntax to tool syntax unmarkup inverse of markup totex convert from tool syntax to TeX/latex markup nt `tangle' the tool form of the noweb file mnt discover roots, then act like nt noidx insert indexing and cross-reference information for latex finduses finds uses of identifiers These pieces are combined by the scripts in the shell directory to provide more than just weaving and tangling: noweb analog of nuweb notangle analog of TANGLE noweave analog of WEAVE nountangle tangle, but keep interleaved documentation in comments noroots print names of all root chunks in a noweb file nocount count number of lines of code and documentation. nodefs extract defined identifiers for noweave -indexfrom noindex build an external index for multi-file documents noweb has been used for four years both at Princeton and elsewhere. It has been used for tens of thousands of lines of code in such languages as awk, C, C++, Icon, Modula-3, PAL, perl, Promela, and Standard ML. If you already know you want to use noweb, you need only install it and read the manual page. If you're just curious about noweb, a sales pitch appears in the technical report in xdoc/ieee.tex. This paper describes version 2.3, so it's somewhat out of date. WHAT YOU GET IN THIS DISTRIBUTION This distribution contains the following directories: contrib software contributed by noweb users examples parts of noweb programs in different languages icon Icon code for nonstandard weave and cross-referencer lib noweave's cross-referencer shell the shell scripts that make up the actual commands src source code for nt and markup tex supporting tex code for /usr/local/lib/tex/macros xdoc man pages and a technical report (named to be unpacked last) where appropriate, these directories have README files of their own. Distributions available by ftp also have DOS binaries, which are always out of date: DOS zip file containing old MS-DOS binaries WEAVING --- A TAR PIT The worst aspect of literate programming is the enormous amount of time wasted wrangling over what ``woven'' output should look like. Although noweb does no prettyprinting, it is not entirely immune--- several people have complained about noweave's output or have sent me changes that add more options to noweave. I resisted for years, but with version 2.5 I finally succumbed. I let the number of options to noweave double, and I have provided for too many options and hooks for customizing the latex output. I won't let it happen again. noweb doesn't try to be all things to all programmers, but it is very easy to change. If you don't like noweave's formatting, you can read tex/support.nw to learn how to customize it; look for the words ``style hook.'' (Reading noweb.sty directly is not recommended.) For simple formatting, it might be easier to throw away noweave and make your own. To help you get started, the shell directory contains noweave.simple, a simplified version of noweave that Dave Hanson created for use with C programs (it can't handle code with @ signs). The article in xdoc/ieee.tex explains the intermediate language that noweb uses to represent literate programs. The intermediate language makes it possible to extend noweave with a language-dependent prettyprinter, as shown by contributions of an Icon prettyprinter by Kostas Oikonomou and a guarded-command prettyprinter by Conrado Martinez-Parra. (I haven't written a prettyprinter myself because my experience with Spider taught me that prettyprinting is far more trouble than it's worth.) Further contributions of prettyprinters are welcome. noweb comes with two cross-referencers for use with noweave. The standard one is written in awk, because that's what everybody has. There is also one written in Icon, which is slightly better because it ignores case when alphabetizing chunk names. See the INSTALL file for more details. Cross-referencing makes formatting even more of a tar pit; the cross-referencer itself takes about 300 lines, and extensive LaTeX support is also required. I haven't made the attempt to write cross-reference code for plain TeX. Anyone who has ideas for reducing the number of options or for other ways to restore sanity to the situation is urged to write to norman@bellcore.com. INDEX AND IDENTIFIER CROSS-REFERENCE To noweb, any string of nonwhite characters can be an identifier. A human being or a language-dependent tool must mark definitions of identifiers; noweb finds the uses using a language-independent algorithm. The algorithm relies on an idea taken from the lexical conventions of Standard ML. Characters are divided into three classes: alphanumerics, symbols, and delimiters. If an identifier begins with an alphanumeric, it must be delimited on the left by a symbol or a delimiter. If it begins with a symbol, it must be delimited on the left by an alphanumeric or a delimiter. If it begins with a delimiter, there are no restrictions on the character immediately to the left. Similar rules apply on the right-hand side. The default classifications are chosen to make sense for commonly used programming languages, so that noweb will not recognize `zip' when it sees `zippy', or `++' when it sees `++:='. This trick works surprisingly well, but it does not prevent noweb from spotting identifiers in comments or string literals. The basic assumption in noweb is that a human being will identify definitions using the @ %def mumble foo quux construct. I have, however, found it very useful to write simple filters that attempt to identify global definitions automatically. Filters for Icon, TeX, and yacc all take about 30 lines of Icon code and are included in the noweb distribution. Contributions for other languages are encouraged. If you write a filter of your own, you can put it in the $LIB directory with a name like `autodefs.pascal'. noweave -index works well for short programs, but nodefs, noindex, and noweave -indexfrom are there for large multi-file programs, See the noindex man page for details. NOTES xdoc/ieee.* contains a paper that has been submitted to IEEE Software. You must `make install' before attempting to format the paper, since it uses the noweb document style option. This paper doesn't discuss features that are new in version 2.5. The paper documents the representation of noweb files that is used by the noweb tools, in case you want to write any tools of your own. Simple tools (e.g. count the number of lines of interleaved documentation) are trivial. If you write any tools, or you want tools written (e.g. prettyprinters, index generators), let me know. The icon directory contains Icon versions of many of the pipeline stages. If you want to adapt noweb to work with a text processor other than TeX or latex, they might provide a better starting point. I confess that the whole system should have been written in Icon from the beginning, but I'm not going to do it over. Icon is available by anonymous ftp from cs.arizona.edu. I have a standing offer open to troff users: I will adapt noweb to troff if you will tell me what the output should look like and you will try to use the results. Thanks to Preston Briggs for the Aho-Corasick recognizer, and for helpful discussions. Thanks to Dave Hanson for cpif. Thanks to Dave Love for LaTeX wizardry. Thanks to Joseph Reynolds for prodding me to fix [[...]]. Thanks to Lee Wittenberg for the DOS binaries. Send comments or questions to norman@bellcore.com. I enjoy hearing from noweb users; if you have enjoyed noweb, why not send me a local postcard for my collection? My address is: Norman Ramsey Bellcore 445 South Street Morristown, New Jersey 07960 USA COPYRIGHT Noweb is copyright 1989-1993 by Norman Ramsey. All rights reserved. You may use and distribute noweb for any purpose, for free. You may modify noweb and create derived works, provided you retain the copyright notice, but the result may not be called noweb without my written consent. You may not sell noweb itself, but you may do anything you like with programs created with noweb. Noweb is not a Bellcore product. Bellcore makes no warranty and accepts no liability for any software in this distribution. If you find something useful, we're all surprised. ================================================================================ Archive-Date: Thu, 28 Oct 1993 18:50:33 CST Sender: LP-Mgr@SHSU.edu From: greyham@research.canon.oz.au (Graham Stoney) Reply-To: LitProg@SHSU.edu, greyham@RESEARCH.CANON.OZ.AU Subject: An Automatic C++ documentation compilation project. Message-ID: Keywords: c2man, C, C++, Literate Programming, Documentation Date: Thu, 28 Oct 1993 08:42:39 GMT To: LitProg@SHSU.EDU Writing and maintaining documentation has often been a thorn in the side of the Software Engineer and Programmer. After spending a great deal of time and effort writing documentation about a program or software system, the code invariably changes, quickly rendering the documentation out of date. The documentation becomes misleading, gets neglected, and quickly becomes useless. "Literate Programming" is one approach to solving this problem. It effectively introduces a whole new (typesetting) language, requires a quite radical shift on the part of the "non-literate" programmer and still requires a good deal of effort on the part of the programmer[1]. I'd like to suggest a different approach which lies considerably closer to more traditional programming practices, and can offer quite immediate benefits when functional interface documentation is the main documentation required. 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. Whilst the idea of extracting documentation from comments in source code is by no means new, the difference here is that the comments actually form part of the grammar of the language recognised by the documentation compiler[2]. Comments should not repeat information that is already represented in the program code; for instance, a comment describing a function argument should not repeat the name and type of that argument (since that information has already been included, for the compiler), but should appear near the argument. For example, in C, the programmer should write this: /* include an example in the article */ enum Result example(int page /* page it appears on */); Rather than this: /* include an example in the article * * PARAMETERS: * int page page it appears on * * RETURNS: * RESULT_YES The readers agreed * RESULT_NO The readers disagreed * RESULT_YOURE_JOKING The readers disagreed strongly * RESULT_BLANK_LOOKS The readers didn't understand */ enum Result example(int page); Also in this example, the documentation compiler knows the possible enumerated values that the function can return (as does the "real" compiler), so it is unnecessary for the programmer to restate them. The comments need simply be included in the definition for "enum Result" for the "RETURNS" information to be generated automatically: enum Result { RESULT_YES, /* The readers agreed */ RESULT_NO, /* The readers disagreed */ RESULT_YOURE_JOKING, /* The readers disagreed strongly */ RESULT_BLANK_LOOKS /* The readers didn't understand */ }; Critics have suggested that the latter style in the example is easier to read for someone wishing to call the function in question. Of course, this is a style question which depends on each person's tastes; but the criticism is tied to the notion that the source code needs to look "beautiful" because it is the primary reference for someone wishing to use that function. This becomes much less significant once documentation is available which is known to _always_ be up to date. Of course, the latter style takes longer to write and maintain, and can become out of date should the name or type of the parameter be changed, yet the comment get neglected. I have implemented one such documentation compiler for the C language called "c2man", which is freely available[3]. The response from users has been extremely encouraging; I suspect this is partly because of the wide variety of styles of comment placement that are recognised: it often correctly recognises comments that weren't written with c2man in mind at all. While it's use is focused solely on functional interface documentation and it doesn't have anywhere near the power of a full Literate Programming system, the focus is on reducing the effort required by the programmer to the absolute minimum, and seeing how much documentation we can get essentially "for free". Many people have requested C++ support be added to c2man, and I suspect that this philosophy would be even more suitable and powerful for documenting interfaces to C++ classes automatically. Here is an example of how I envisage this philosophy would work when applied to C++. It's interesting to note that this code was written a couple of years ago exactly as you see it here, without the idea of generating documentation from it in mind at all: // generic Timer class class Timer { private: static int numactive; // number of constructed timers. static Timer *first; // first one in list. Timer *next; // next one in linked list. Time ticksdiff; // ticks we take to expire once at front. enum { INACTIVE, // timer is not in chain. STARTED, // one-shot RUNNING // continuous. } state; // original interrupt vector value. static void interrupt (far *old_vector)(...); void (*timeout_function)(int); // function called when we time out int timeout_parameter; // gets passed to timeout_function Time duration; // timer length (ticks) static void interrupt far tick(...); // clock tick routine. void insert(); // add into active chain. void remove(); // remove from active chain. void set(Time milliseconds); // set duration from ms. public: // constructor Timer(Time time=0, // milliseconds void (*function)(int)=0, // called at timeout int param=-1); // param for function // destructor ~Timer(); // start (or restart) a timer running. void Start(); void Start(Time duration); // how long to run for // start a timer running continuous. void Run(); // stop a timer. void Stop(); // is a timer active? boolean Active() const { return state != INACTIVE; }; }; Processing this class declaration could generate the following automatically: NAME Timer - generic timer class SYNOPSIS class Timer { public: Timer(Time time=0, void (*function)(int)=0, int param=-1); ~Timer(); void Start(); void Start(Time duration); void Run(); void Stop(); boolean Active() const; }; PARAMETERS Time time Milliseconds void (*function)(int) called at timeout. int param Param for function. Time duration How long to run for. DESCRIPTION Timer Constructor ~Timer Destructor Start Start (or restart) a timer running. Run Start a timer running continuous. Stop Stop a timer. Active Is a timer active?. It should also be possible to extract this information from the implementation of the class (rather than the declaration), if that's where the user prefers to put the comments describing each member function and their parameters. Unfortunately, at present I do not have sufficient spare time to make the additions to c2man required to support C++. It would be a great contribution to the C++ community, not to mention the documentation time saved by themselves, for someone involved in C++ work to add this support and release the result[4]. If you work with a team developing C++ code, please consider having one of your developers on a ``Usenet Sabbatical'' to extend this philosophy to C++, and start reaping the benefits in documentation time savings. It could also make an ideal Computer Science student compiler project. Please contact me via E-mail if you are interested in undertaking such a project. Graham Stoney Footnotes: 1. Advocates of Literate Programming would argue that Literate Programming is much more than snazzy documents and that it encourages this extra effort to focus early on in the design of the software, which pays off later. 2. To get a better idea, see the file grammar.y in the c2man distribution. 3. c2man has been posted on comp.sources.reviewed. It should be available from: comp.sources.reviewed archive volume 3, or ask archie. N.America: ftp.wustl.edu:/usenet/comp.sources.reviewed/volume03/c2man* Europe: ftp.informatik.uni-stuttgart.de: /pub/archive/comp.sources/reviewed/c2man* Patches: lth.se:/pub/netnews/sources.bugs/volume93/sep/c2man* 4. c2man's copyright requires that all derivative works remain freely available. -- Graham Stoney, Hardware/Software Engineer Canon Information Systems Research Australia Ph: + 61 2 805 2909 Fax: + 61 2 805 2929 ================================================================================ Archive-Date: Fri, 29 Oct 1993 11:13:17 CST Sender: LP-Mgr@SHSU.edu Subject: FrameMaker Message-ID: <1993Oct28.170420.18976@kocrsv01.delcoelect.com> From: c21vc@kocrsv01.delcoelect.com (Venkataraman Chandrasekhar) Reply-To: LitProg@SHSU.edu, c21vc@KOCRSV01.DELCOELECT.COM Date: Thu, 28 Oct 1993 17:04:20 GMT To: LitProg@SHSU.EDU I am wondering whether someone will post some details on FrameMaker. Is it a desktop publishing program ? (I did note that it has hypertext capabilities.) Several years ago, I played around with PagMaker a little bit. How would FrameMaker compare with Interleaf or Teamwork (the two packages available here) in the general type of functions provided. Does it belong in teh same (utility) class or would it be used for other purposes usually ? Thanks. Shaker ================================================================================ Archive-Date: Fri, 29 Oct 1993 11:14:52 CST Sender: LP-Mgr@SHSU.edu Subject: Re: FrameMaker Message-ID: <1993Oct29.135530.1050@vmark.co.uk> From: mynard@vmark.co.uk (Alan Mynard) Reply-To: LitProg@SHSU.edu, mynard@VMARK.CO.UK Date: Fri, 29 Oct 93 13:55:30 GMT To: LitProg@SHSU.EDU From article <1993Oct28.170420.18976@kocrsv01.delcoelect.com>, by c21vc@kocrsv01.delcoelect.com (Venkataraman Chandrasekhar): > > I am wondering whether someone will post some details on FrameMaker. > Is it a desktop publishing program ? (I did note that it has hypertext > capabilities.) Several years ago, I played around with PagMaker a little bit. > > How would FrameMaker compare with Interleaf or Teamwork (the two packages > available here) in the general type of functions provided. Does it belong in teh > same (utility) class or would it be used for other purposes usually ? FrameMakeer is a DTP with similar capabilities to Interleaf. It runs on UNIX workstations and there is a cut-down version that runs under Windows on PC's. Alan -- Alan Mynard --- VMark Software Ltd. eMail: mynard@vmark.co.uk \/o o\/ Power House, Davy Avenue, Tel: +44 908 234990 \ | / Knowlhill, Milton Keynes, Fax: +44 908 234992 |v| MK5 8HJ, UK ================================================================================ Archive-Date: Fri, 29 Oct 1993 11:15:05 CST Sender: LP-Mgr@SHSU.edu Subject: Re: An Automatic C++ documentation compilation p Message-ID: <1993Oct29.132036.12489@cas.org> From: rhl20@cas.org (Robert H. Ledwith) Date: Fri, 29 Oct 1993 13:20:36 GMT Reply-To: LitProg@SHSU.edu, rhl20@cas.org To: LitProg@SHSU.EDU I am currently struggling with creating low-maintenance C++ documentation and have an additional comment concerning automatically collecting and presenting documentation for C++ programs. This comment actually applies to any object-oriented programming language. When a programmer is faced with documentation for a class, it is desirable to have the entire interface for the class presented in a complete and well organized manner. In addition to the problems and issues involved in presenting information for C language program units, one is now faced with inheritance. If class B is derived from class A, when I inspect the documentation for class B, I wish to see class A's public interface as well. This situation is potentially very messy, when you begin to take into account multiple inheritance and run-time binding (such as mixins). When I've looked at this problem, I have been unable to come up with any modest-effort solutions to it. Has anyone else thought about this problem and come up with workable solutions? ================================================================================ Archive-Date: Fri, 29 Oct 1993 11:15:22 CST Sender: LP-Mgr@SHSU.edu Subject: Re: New version of WinWordWEB Message-ID: <2ar1j4INNsp9@rs18.hrz.th-darmstadt.de> From: schrod@iti.informatik.th-darmstadt.de (Joachim Schrod) Reply-To: LitProg@SHSU.edu, schrod@ITI.INFORMATIK.TH-DARMSTADT.DE Date: 29 Oct 1993 12:16:36 GMT To: LitProg@SHSU.EDU In article <16900707@MVB.SAIC.COM>, Lee Wittenberg writes: > Stephen McKearney has made a few improvements to the original > WinWordWEB, [...] > I've made > the new, improved version (wordweb2.zip) available for anonymous ftp > in the pub/leew directory of bart.kean.edu. The original version is > still there, as well. I understand that there are several ftp sites > out there that also make copies of WordWEB available. I'd appreciate > it if everyone could keep traffic on bart down to a minimum, and wait > until these other sites get the new version (assuming that they do). Literate Programming Archive: ftp.th-darmstadt.de [130.83.55.75] directory pub/programming/literate-programming/machines/ms-dos files wordweb* (Usually I mirror weekly, on Sundays. I triggered it by hand this time.) > This brings me to the problem of maintenance. WinWordWEB was intended > to be an unsupported product, but there seems to be enough interest in > it that I feel a moral responsibility to provide some sort of > support. :-) You're listed as the contact person at the LPA. ;-) -- Joachim [THD Literate Programming Archive, maintainer] =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= Joachim Schrod Email: schrod@iti.informatik.th-darmstadt.de Computer Science Department Technical University of Darmstadt, Germany ================================================================================ Archive-Date: Fri, 29 Oct 1993 11:15:50 CST Sender: LP-Mgr@SHSU.edu Subject: Practical language independecy Message-ID: From: jacojn@inet.uni-c.dk (Jacob Nielsen) Reply-To: LitProg@SHSU.edu, jacojn@INET.UNI-C.DK Date: Fri, 29 Oct 1993 14:47:44 GMT To: LitProg@SHSU.EDU When we're programming in a language independent literate programming system, (e.g. nuweb), why not make the programming language clear to the reader? Normally we do one of two things: 1) rely on the readers expertice with programming languages to detect which language we're programming in now. 2) mention the programming language in the documentation text. Both options have clear drawbacks (required expertice when reading the documentation and bad language in the text) These problems could be solved by making the choice of programming language a part of the definition of a scrap/macro. So, instead of writing (in nuweb): This part is written in the C language (see [K&R])
= main() { } we could write something like:
= main() { } \smallfont{Scrap written in the C language} This would also eliminate the need for a web comment (like '@%') used to hide things like '-*-*-C++-*-*-', that users of the emacs nuweb mode can use. As an user of nuweb, I suggest that we adopt an new optional option '@L' in the definition of scraps, that specifies the language of the scrap. It should be optional because in projects where we have one main language, it could clutter the documentation with multiple 'language: C++' and therefore be of no practical use. PS: English is not my native language, so please bare with my typos :-) Jacob Nielsen -- Email: jacojn@inet.uni-c.dk (my private account) or bc898574@bbar.dth.dk (my account at the university) ================================================================================ Archive-Date: Fri, 29 Oct 1993 11:15:55 CST Sender: LP-Mgr@SHSU.edu Subject: Re: Reference to Skinner's article on writing Message-ID: <1993Oct28.145528.12631@kocrsv01.delcoelect.com> From: c21vc@kocrsv01.delcoelect.com (Venkataraman Chandrasekhar) Reply-To: LitProg@SHSU.edu, c21vc@KOCRSV01.DELCOELECT.COM Date: Thu, 28 Oct 1993 14:55:28 GMT To: LitProg@SHSU.EDU I would like to make a couple of points here. 1. Skinner has devoted all his professional life to discovering basic (learning processes and) responding (behaving/acting) processes that happen at particular instances in time as a function of several variables. His statement of responding processes do not appeal to a behavior initiating mind; what happens in the mind is not ignored; it is explained as more effects (and not causes of responses i.e. dependent variable instead of independent variable). I am aware that his conclusions are far from universally accepted. (Based on my experience, I have no doubt that something like what he says is correct; or as Kennneth McCorquadale wrote about this approach to verbal behavior, in response to Chomsky's scathing review of Skinner's book 'Verbal Behavior': 'Like it or not, the camel's nose is in the tent'. (This review is in the Journal of Experimental Analysis of Behavior; this journal has a good index.) My point is this 'outline editor' may have somthing else going for it; the method is developed by some one who has thought a lot about the fundamental process by which actions come out of individuals; Skinner also used the method in his writings during the last few years. 2. He also says in the article that this can be easily programmed. I am wondering whether someone is interested in attempting something like this. I can help. Of course, the Skinner's family and the journal have to be contacted to get permission; I can help here also. Shaker ================================================================================ Archive-Date: Fri, 29 Oct 1993 11:16:03 CST Sender: LP-Mgr@SHSU.edu Subject: c2man reviews needed by Friday 5 November 1993 (Hassle, Hassle, ...) Message-ID: From: greyham@research.canon.oz.au (Graham Stoney) Reply-To: LitProg@SHSU.edu, greyham@RESEARCH.CANON.OZ.AU Date: Fri, 29 Oct 1993 08:00:58 GMT Keywords: c2man, troff, documentation, review To: LitProg@SHSU.EDU This is a final prod to anyone interested in reviewing patches 10 thru 17 to c2man. I'd like to get all reviews in by Friday 5 November 1993 so these patches can be posted as soon as possible. c2man is an automatic documentation generator which generates functional interface documentation from C source code and comments. Patches 10 thru 17 to c2man are currently under review in comp.sources.reviewed. If you are a C user and are interested in not having to write documentation manually, please consider reviewing these patches. With this new version of c2man, OS/2 and MSDOS are supported, and texinfo output can be generated in addition to the usual nroff -man. No reviews have been recieved as yet, which is suprising considering the wide potential user base. It may be that everyone is leaving it to everyone else; in other words, to no-one - and that makes the whole review process break down. We want patches expedited, so please consider participating in this review, and if you do fetch them, _please send in a review_. If you're short of time, you don't need a big speil; just a "OK" or "It's busted" is fine, but please send _something_ in. Also, If you are already using c2man at patchlevel 17, please consider sending in a review. [comp.sources.reviewed Moderator's info] This package contains a C program to convert C source to `nroff -man' input, plus 7 patch files and a shell dirver to unpack the lot. This product has been reviewed and posted before. Check it out. If you are interested in *reviewing* this package send a mail message to the csr mail-server: To: csr@cc.purdue.edu Subject: send c2man and the mail server will send you the stuff. Initial comments: - I unpacked the parts, and applied the patches. - I include a script to do the same for you - I configured the product and it runs on sun4-sunos4.1.3. - you get 17 parts, but 3 of them are padding for the mail-server If you need help with the mail-server send a note like To: csr@cc.purdue.edu Subject: help Graham -- Graham Stoney, Hardware/Software Engineer Canon Information Systems Research Australia Ph: + 61 2 805 2909 Fax: + 61 2 805 2929 ================================================================================ Archive-Date: Fri, 29 Oct 1993 11:16:15 CST Sender: LP-Mgr@SHSU.edu Subject: Re: Literate programming in Framemaker. Message-ID: <1993Oct29.105928.10670@cs.wm.edu> From: collins@ny.cs.wm.edu (Bob Collins) Reply-To: LitProg@SHSU.edu, collins@NY.CS.WM.EDU Date: Fri, 29 Oct 1993 10:59:28 GMT To: LitProg@SHSU.EDU Folks, This is my one response to my complaint about TeX and Knuth. I have the feeling this might turn into a jihad. FrameMaker is a commercial product suitable for producing large printed and hypertext documents, especially those that need maintenance and involve technical material and drawings. FrameMaker cannot do all things and some of what it does it does poorly. FrameMaker is not even my word processor of choice, but I use it because of its universality. Joachim Schrod wrote > How do you edit your FrameMaker documents on more than 40 different > operating systems, ranging from 8086 PCs to Crays? FrameMaker is available on all the major platforms that can support it, that is, that have sufficient power and memory and that allow bitmap displays. This means most Unix systems, Macs, and MS Windows. Don't blame FrameMaker if it doesn't work on an AT. One cannot have its power for free. TeX is a filter -- all it does is translate from one form to another, like a compiler. Therefore it needs far fewer resources. FrameMaker integrates what TeX does, what your favorite editor does, what previewers do, what drawing programs do, and what dvi2lp utilities do. Face it -- how many of you wished that you could edit your preview when you found some error that you overlooked? How many of you preview on an 8086? Joachim Schrod wrote > How do you use FrameMaker in a convenient way as a background system? FrameMaker (on Unix) has both a macro system and a batch system. Both allow background processing. [In a silly moment I might ask, how do you allow foreground processing of TeX commands while you edit?] Joachim Schrod wrote > How do you use many languages? (Remember: Not everyone writes in > English...) Last I checked, FrameMaker is available in 11 languages. (12, if you separate American English and Proper English.) This support is available in the dictionaries, thesaurus, system variables (like dates), and numbering schemes. Mark Friedman wrote > I'll add 2 even ``lower-end'' systems to the editing list --- I often take > notes & revise drafts on an _ancient_ Tandy T102 (not even MS-DOS, but it can > spit out ascii), and I have 3 daughters (ages 11 to 18) that ``share'' an > 80286 to (La)TeX documents created on a trio of (also ancient) Apple ]['s. > The point, of course is quite simple --- if it can produce ascii outout, > _anything_ can be used for entry & editing. One can import text into FrameMaker. FrameMaker will even get rid of extraneous spaces and turn straight quote marks into curly ones while it imports (if you want). In addition, FrameMaker supports MML import. MML stands for Maker Mark-up Language and is a SMGL-like form for typographic conventions. So your kids can edit their instructions in their text, read it into FrameMaker, and then edit the preview-like display. Mark Friedman wrote > As for the oft cited difficulty of learning LaTeX, my daughters have done _all_ > their school reports since 3rd grade as well as lots of other ``documents'' > (my 15 year old produces Girl Scout troop meeting minutes, plans & budgets), > in English, French, German, Spanish and even ASL (American Sign Language --- > a one-off report using a wonderful `hands' Metafont file). Overkill? Absolutely, > but they happen to love it (they're even more critical of sloppy or ugly > documents that I am, and I thought I was the perfectionist in the family). > It has also led to various amusing incidents, like when my oldest was in 7th > grade her English teacher stated that there was ``only one right way to format > a bibliograpy''. Allyson's response was to take my copy of the Chicago Manual of > Style to school, along with about a dozen versions of her assignment's > bibliography, all formatted by different .bst styles, and ask which one > was the ``right'' one... Well, Mr. Friedman has a smart set of kids. I congratulate them and him. I have my own set of computer-literate kid stories, and I will be pleased to share them. I wish all children had entre to computer-wise parents and equipment at the earliest age. It would help me as a university professor. [My favorite kid story is how my son, when 5, learned how to use a paint program by memorizing what the menus did. He could not read, but he knew the alphabet.] However, I have gone through the hassle of trying to help graduate students try to write using LaTex. The learning curve is steeeep. In fact, some of our faculty couldn't figure out how to get rid of a space before a grammar production in our comprehensive examination question list. The number of macros (written by different folks) confused the issue. The smartest people can get turned off by TeX. Is literate programming closed to them? Let's get serious, however. For those who know, TeX works great. Just like punch cards for editing. However, most people found interactive editing much easier. And those who were used to punch cards sometimes found it difficult or unnecessary to change. And they were right. You can do anything you want with a punch card. Make a wish list for literate programming. Don't worry about how it can be accomplished, or how the typesetting is done. I think that most of us would like to edit the finished product rather than the marked-up product. [I would like to do it by voice, e.g., Bob Collins: Show me the code fragment for the input loop. Computer: Did you mean code fragment or chunk?] At the least, this means interactive TeX. Let's aim for that. Meanwhile, I think that FrameMaker offers a reasonable alternative. These are my final words. Flame on. Bob Collins, collins@cs.wm.edu CS Dept, Coll of Wm & Mary (est 1693) ================================================================================ Archive-Date: Fri, 29 Oct 1993 11:26:43 CST Sender: LP-Mgr@SHSU.edu Subject: Re: Inline comments and abstraction Message-ID: From: bdubbs@tis.kelly.af.mil Date: Fri, 29 Oct 1993 13:38:33 GMT Reply-To: LitProg@SHSU.edu, bdubbs@tis.kelly.af.mil To: LitProg@SHSU.EDU In <2177@se.alcbel.be>, cgra@btma74.nohost.nodomain (Chris Gray) writes: > >In article <2abjai$965@TAMUTS.TAMU.EDU>, bdubbs@cs.tamu.edu (Bruce Dubbs) writes: > >In article <16782125@mvb.saic.com>, Lee Wittenberg wrote: > >>The problem with `chunk' is that it does have this use in Psychology. >>The more complete term is `cognitive chunk'. I have proposed the term >>`cognitve block' in a paper now being refereed. > >Ooerr. In that context `cognitive block' makes me think of `mental block' >or `writer's block'. > I see. We are talking about nouns and you think about verbs. ;-) -- Bruce ================================================================================ Archive-Date: Fri, 29 Oct 1993 11:51:33 CST Sender: LP-Mgr@SHSU.edu From: rudolf@ergon.ch (Jim Rudolf) Reply-To: LitProg@SHSU.edu, rudolf@ERGON.CH Subject: FrameMaker for LP output, not input Message-ID: Date: Fri, 29 Oct 1993 14:44:20 GMT To: LitProg@SHSU.EDU Charles Bass writes: >I think that your idea with framemaker is the only way to go. Personally, I think using FrameMaker is a good idea, but not necessarily by *editing* in FrameMaker. We are just a bunch of programmers who use vi and work fast in it. We want to be able to document our code too, and embedding the doc in the source code (keeping in mind the readability of the source for us programmers, of course) means we are more likely to update the doc when we update the code. Our solution was to write a couple perl scripts to do documentation generation for us. One script scans the source file for a few keywords that can describe the entire module or individual procedures. Once all the info for a file is collected, another set of scripts will create a file either in man page or MML format. The two formats are quite different, as the man page format is used internally, and the MML format is used to make a FrameMaker book for customers. Other back-end scripts could easily be written when needed. We've found this to be a good combination for us. Has anyone else had any experience (good or otherwise) with this approach? Cheers, Jim -- Jim Rudolf Ergon Informatik AG rudolf@ergon.ch ================================================================================ Archive-Date: Fri, 29 Oct 1993 12:04:29 CST Sender: LP-Mgr@SHSU.edu Subject: Re: FrameMaker Message-ID: <2aremh$gsq@tcsi.tcs.com> From: sriram@glock.tcs.com (Sriram Srinivasan) Reply-To: LitProg@SHSU.edu, sriram@GLOCK.TCS.COM Date: 29 Oct 1993 16:00:17 GMT To: LitProg@SHSU.EDU In article <1993Oct28.170420.18976@kocrsv01.delcoelect.com>, c21vc@kocrsv01.delcoelect.com (Venkataraman Chandrasekhar) writes: > > How would FrameMaker compare with Interleaf or Teamwork (the two packages > available here) in the general type of functions provided. Does it belong in teh > same (utility) class or would it be used for other purposes usually ? FrameMaker competes directly with Interleaf. Amusing aside : If you type "InterLeaf" in a FrameMaker document, the spelling checker asks if you want to correct it to "FrameMaker". Sriram (sriram@tcs.com) ================================================================================ Archive-Date: Fri, 29 Oct 1993 13:07:08 CST Sender: LP-Mgr@SHSU.edu Date: Fri, 29 Oct 93 13:03:56 CDT From: preston@cs.rice.edu (Preston Briggs) Reply-To: LitProg@SHSU.edu, preston@CS.RICE.EDU Message-ID: <9310291803.AA07644@dawn.cs.rice.edu> To: LitProg@shsu.edu Subject: mailing list or newsgroup? Are we a newsgroup yet? Is it supposed to be comp.programming.literate? Thanks, Preston ================================================================================ Archive-Date: Fri, 29 Oct 1993 17:21:11 CST Sender: LP-Mgr@SHSU.edu Date: Fri, 29 Oct 93 18:18:59 -0400 From: koopman@sgi84.ctc.com (Michael G. Koopman) Message-ID: <9310292218.AA21096@sgi84.ctc.com> To: LitProg@SHSU.edu, collins@NY.CS.WM.EDU CC: LitProg@SHSU.EDU Subject: Literate programming in Framemaker. Reply-To: LitProg@SHSU.edu, koopman@ctc.com Bob Collins wrote: > This is my one response to my complaint about TeX and Knuth. >I have the feeling this might turn into a jihad. FrameMaker is >a commercial product suitable for producing large printed and >hypertext documents, especially those that need maintenance and >involve technical material and drawings. FrameMaker cannot do all >things and some of what it does it does poorly. FrameMaker is >not even my word processor of choice, but I use it because of >its universality. I don't believe you'll see an uprising from your comments on TeX. I have not heard anyone pining over the punch card machine nor against an interactive TeX editor/previewer. The TeX hacks promote the capability, portability and succintness of the language. Whether or not FrameMaker is as clever as TeX seems somewhat irrelevant. If you want a FrameMaker web then what qualities of the web are critical and which of these 'requirements' are met by FrameMaker and not met by TeX. That is, why does literate programming in FrameMaker detract from literate programming in TeX? Does FrameMaker read TeX input, or more importantly, can FrameMaker read a CWEB, FWEB, etc. web and not munge it beyond recognition? Let's not hack each other up in religious wars over the "right" editor or typesetting mechanism. Let's focus on the benefits and needed improvements in the literate programming techniques at hand, instead. Peace be with the Literati, Michael Koopman (mike) e-mail: koopman@ctc.com Concurrent Technologies Corporation phone: +1-814-269-2637 1450 Scalp Avenue telefax: +1-814-269-2666 Johnstown, PA 15904-3321 USA ICBM: 40-15'N-78-50'W ================================================================================ Archive-Date: Fri, 29 Oct 1993 20:40:09 CST Sender: LP-Mgr@SHSU.edu Date: Fri, 29 Oct 1993 21:06:53 -0400 From: ae1181t@stnfor.ae.ge.com (Osman F Buyukisik) Reply-To: LitProg@SHSU.edu, ae1181t@STNFOR.AE.GE.COM Message-ID: <9310300106.AA18670@stnfor.ae.ge.com> To: LitProg@SHSU.edu Subject: Re: FrameMaker for LP output, not input People seems to be missing the main point about litprog. It is not just a documentation scheme! You start from the design phase and use whatever form of editor/TP you want to explain the code and write the code in a way that is independent of the whims of the compiler that you will use. In the end, the final product should resemble a `book'. Because of these points I dont think c2man and others like it are litprog tools. You can use framemaker/interleaf but someone has to write some expansion to it so that `tangle' command is available in the menu (like the WinWordWeb). No one is forcing TeX/LateX but these tools are FREE and widely available. People should not be flaming each other instead if you want a framemaker litprog tool just create it and announce it to the net. For myself I cannot see how hypertext helps since I like the printed output! I use interleaf at work and all the formulas and graphs do not look the same on the screen as printed on paper, and are hard on the eyes. My $0.02 contribution. Osman ================================================================================ Archive-Date: Fri, 29 Oct 1993 20:45:44 CST Sender: LP-Mgr@SHSU.edu From: calderwt@redbaron.wosc.osshe.edu (Timothy Calderwood) Reply-To: LitProg@SHSU.edu, calderwt@REDBARON.WOSC.OSSHE.EDU Subject: Fast Sort Date: Fri, 29 Oct 1993 23:51:33 GMT Message-ID: To: LitProg@SHSU.EDU I am not sure this is where to ask, but for a class project I have, I need a really fast sort on 10,000 random integers. If anybody out their has any algorithms or code that might help, drop me a note. I really dont care how ugly the code might be. Thanks ================================================================================ Archive-Date: Fri, 29 Oct 1993 21:50:41 CST Sender: LP-Mgr@SHSU.edu From: marcus@x4u2.desy.de (Marcus Speh) Reply-To: LitProg@SHSU.edu, marcus@X4U2.DESY.DE Subject: Re: An Automatic C++ documentation compilation project. Message-ID: Date: Sat, 30 Oct 1993 01:19:46 GMT To: LitProg@SHSU.EDU The following is taken from Leif Loennblad's "CLHEP-Class Library for High Energy Physics" project. Leif advocates and distributes the 'classdoc' awk(1) script which I have found to be very useful too. It is one of the options in an ongoing effort to make C++ library code (in HEP) fully accessible through the World Wide Web (since man pages can be turned into HTML on the fly). ---------------------- from CLHEP/README -------------------------- The classdoc program ==================== All the header files in this distribution are written to be easily converted to a unix-style manual page by the classdoc program written by Dag Bruck. I think that this program provides a very easy-to-use class documentation - simply write the code and put in comments where you usually would put them (there are of course also a few small tricks you can use to get nicer output) and classdoc will do the rest. ------------------------------------------------------------------- You can get the classdoc(1) program as part of CLHEP from the freeHEP server in any of the CLHEP releases from freehep.scri.fsu.edu:/hep-projects/CLHEP/ Needless to say: I myself would prefer people would write their code using one of the "true" literate programming tools. But classdoc(1) isnt too bad if you'd like to save the effort. -- ----------------------------------------------------------------------------- Marcus Speh, II.Inst.Theor.Physik,Luruper Chaussee 149, 22761 Hamburg,Germany Phone: +49-40 8998 2178, Fax: +49-40 8998 2267, Private: +49-40 801392 Internet: , ================================================================================ Archive-Date: Sat, 30 Oct 1993 08:28:03 CST Sender: LP-Mgr@SHSU.edu Subject: Quality metrics for OO methods? Message-ID: <93302.223545U17868@uicvm.uic.edu> From: Sikander Waheed Reply-To: LitProg@SHSU.edu, U17868@UICVM.UIC.EDU Date: Fri, 29 Oct 1993 22:35:45 CDT To: LitProg@SHSU.EDU I have two questions: 1. With the advent of Object-Oriented development methods, what are some of the productivity metrics that work better with object-orientation? By productivity here I mean Programmer's productivity. 2. What are some of the Object-Oriented quality metrics? That is only those metrics that are related to OO. Thanks, Sikander ================================================================================ Archive-Date: Sat, 30 Oct 1993 08:28:05 CST Sender: LP-Mgr@SHSU.edu Subject: Re: Inline comments and abstraction Message-ID: <2at316$3hl@thales.cs.umd.edu> From: stewart@cs.umd.edu (G. W. Stewart) Reply-To: LitProg@SHSU.edu, stewart@CS.UMD.EDU Date: 30 Oct 1993 02:53:26 -0400 To: LitProg@SHSU.EDU In article bdubbs@tis.kelly.af.mil writes: #In <2177@se.alcbel.be>, cgra@btma74.nohost.nodomain (Chris Gray) writes: #> #>In article <2abjai$965@TAMUTS.TAMU.EDU>, bdubbs@cs.tamu.edu (Bruce Dubbs) writes: #> #>In article <16782125@mvb.saic.com>, Lee Wittenberg wrote: #> #>>The problem with `chunk' is that it does have this use in Psychology. #>>The more complete term is `cognitive chunk'. I have proposed the term #>>`cognitve block' in a paper now being refereed. #> #>Ooerr. In that context `cognitive block' makes me think of `mental block' #>or `writer's block'. #> # #I see. We are talking about nouns and you think about verbs. ;-) # -- Bruce # A trip to the dictionary is useful here. My American Heritage (1st edition) defines fragment 1. A part broken off or detached from a whole. 2. Something incomplete; an odd bit or piece. 3. An extant part of an unfinished or lost text. and chunck. 1. A thick mass or piece of something. 2. A fair or substantial amount. Definitions, of course, vary from dictionary to dictionary; but the point is that the word "fragment" stresses the relation of the part to the whole, unlike chunk, lump, clump, scrap, etc. It seems to me that "fragment" fits naturally into the literate programming framework, whereas the alternatives are slightly forced. Pete Stewart