Archive-Date: Fri, 14 Jan 1994 04:42:40 CST Sender: LP-Mgr@SHSU.edu From: maavl@cwi.nl (Marc van Leeuwen) Reply-To: LitProg@SHSU.edu, maavl@CWI.NL Subject: Re: GraphBase for PC's Message-ID: Date: Fri, 14 Jan 1994 08:57:09 GMT To: LitProg@SHSU.EDU In article <2h56fg$cha@panix.com>, dsiegel@panix.com (David Siegel) writes: |> |> Where can I pick up a copy [of the Stanford GraphBase]? |> That's at labrea.stanford.edu:/pub/sgb ================================================================================ Archive-Date: Fri, 14 Jan 1994 07:22:43 CST Sender: LP-Mgr@SHSU.edu From: mak@nexor.co.uk (Martijn Koster) Subject: Re: WEB for perl? Message-ID: <1994Jan14.020116.10112@cs.nott.ac.uk> Reply-To: LitProg@SHSU.edu, m.koster@nexor.co.uk Date: Fri, 14 Jan 94 02:01:16 GMT To: LitProg@SHSU.EDU In article <2h21hjINN6i9@life.ai.mit.edu>, rjc@gnu.ai.mit.edu (Ray) writes: |> Is there a version of WEB which works with Perl? If so, where |> can I FTP it? If with "WEB" you mean the World Wide Web, then yes, there is a Perl server that talks HTTP. See http://www.bsdi.com/server/doc/plexus.html -- Martijn __________ Internet: m.koster@nexor.co.uk X-400: C=GB; A= ; P=Nexor; O=Nexor; S=koster; I=M X-500: c=GB@o=NEXOR Ltd@cn=Martijn Koster WWW: http://web.nexor.co.uk/mak/mak.html ================================================================================ Archive-Date: Fri, 14 Jan 1994 11:09:10 CST Sender: LP-Mgr@SHSU.edu From: marcus@x4u2.desy.de (Marcus Speh) Reply-To: LitProg@SHSU.edu, marcus@X4U2.DESY.DE Subject: Re: I think we need a short feature summary... Message-ID: Date: Fri, 14 Jan 1994 16:12:24 GMT To: LitProg@SHSU.EDU I have stumbled on this debate a bit late - hope I got the point. Now, I would like to offer the existing freeHEP database at SCRI, in Tallahassee/FL, for such a collection of descriptive files. The tools FWEB, CWEB, NOWEB and CLiP are already described there (in a format rather like the one used in the FAQ). One advantage of freeHEP is that its contents are automatically browsed by a large database (SPIRES) at SLAC and are also converted into Hypertext for the World-Wide Web. The text files are of course accessible by FTP as well. Anyone who is up to coordinating this collection of dbase files may contact me in the matter. Marcus PS. FYI, the addresses for the documented tools are: FTP: freehep.scri.fsu.edu:/freehep/languages/fweb/FWEB.dbase freehep.scri.fsu.edu:/freehep/languages/cweb/CWEB.dbase freehep.scri.fsu.edu:/freehep/languages/noweb/NOWEB.dbase freehep.scri.fsu.edu:/freehep/languages/clip/CLIP.dbase WWW: http://slacvm.slac.stanford.edu:5080/FIND/FREEHEP/NAME/FWEB/FULL http://slacvm.slac.stanford.edu:5080/FIND/FREEHEP/NAME/CWEB/FULL http://slacvm.slac.stanford.edu:5080/FIND/FREEHEP/NAME/NOWEB/FULL http://slacvm.slac.stanford.edu:5080/FIND/FREEHEP/NAME/CLIP/FULL the address http://heplibw3.slac.stanford.edu/FIND/... is valid as well. Information on WWW is available via FTP from ftp.desy.de, in file: pub/userWWW/projects/Announce/LitProg.txt. -- ----------------------------------------------------------------------------- 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 Email: , -- DECnet: 13313::SPEH ================================================================================ Archive-Date: Fri, 14 Jan 1994 15:10:02 CST Sender: LP-Mgr@SHSU.edu From: preston@dawn.cs.rice.edu (Preston Briggs) Reply-To: LitProg@SHSU.edu, preston@DAWN.CS.RICE.EDU Subject: Re: WEB for perl? Message-ID: Date: Thu, 13 Jan 1994 23:35:00 GMT To: LitProg@SHSU.EDU >> Is there a version of WEB which works with Perl? If so, where can >> I FTP it? Kayvan Sylvan writes: >Any of the language-independant WEBs work. I write Perl programs >in nuweb all the time. You can get it, via anonymous ftp, from cs.rice.edu, in the directory public/preston ================================================================================ Archive-Date: Fri, 14 Jan 1994 16:37:22 CST Sender: LP-Mgr@SHSU.edu From: ridderbusch.pad@sni.de (Frank Ridderbusch, STO SI211) Reply-To: LitProg@SHSU.edu, ridderbusch.pad@SNI.DE Subject: Re: WEB for perl? Date: 14 Jan 1994 20:37:07 GMT Message-ID: To: LitProg@SHSU.EDU >>>>> "Steve" == Steve Daukas writes: In article scd@atria.com (Steve Daukas) writes: Steve> Ray (rjc@gnu.ai.mit.edu) wrote: Steve> : Is there a version of WEB which works with Perl? If so, where Steve> : can I FTP it? Steve> PLEASE let me know too! Steve> Regards, Steve> Steve Look at the FAQ from comp.literate.programming. There are at least two packages, which work with any programming language. The packages, which I have in mind are NUWEB and NOWEB. There are available from most major archives, which carry TeX related stuff (CTAN archives). NUWEB works quite nicely for me. Simple, small and fast. No problem to carry to non UNIX os. -- MfG/Regards /==== Siemens Nixdorf Informationssysteme AG / Ridderbusch / , Abt.: SU MR PD 251 / /./ Riemeke Str. 160 /=== /,== ,===/ /,==, // W-4790 Paderborn, Germany / // / / // / / \ Tel.: (49) 05251-8-35211 / / `==/\ / / / \ NERV:ridderbusch.pad Email: ridderbusch.pad@sni-usa.com (America (North & South)) ridderbusch.pad@sni.de (Rest of world) ================================================================================ Archive-Date: Fri, 14 Jan 1994 16:37:33 CST Sender: LP-Mgr@SHSU.edu From: wayne@tachyon.com (Wayne Sewell) Reply-To: LitProg@SHSU.edu, wayne@TACHYON.COM Subject: Re: WEB for perl? Message-ID: <1994Jan14.140345.964@tachyon.com> Date: 14 Jan 94 14:03:45 CST To: LitProg@SHSU.EDU In article <1994Jan14.020116.10112@cs.nott.ac.uk>, mak@nexor.co.uk (Martijn Koster) writes: > In article <2h21hjINN6i9@life.ai.mit.edu>, rjc@gnu.ai.mit.edu (Ray) writes: > |> Is there a version of WEB which works with Perl? If so, where > |> can I FTP it? > > If with "WEB" you mean the World Wide Web, then yes, there is a Perl server > that talks HTTP. See http://www.bsdi.com/server/doc/plexus.html > In the realm of literate programming (and this message was posted to comp.programming.literate), WEB has a completely different meaning. It is a combination documentation and programming language developed by Donald Knuth. There is absolutely no relation between the WEB language and the World Wide Web. The original WEB was designed for Pascal, but variants have been developed for many other programming languages. The poster is asking if there is a variant for Perl. -- ============================================================================== Wayne Sewell |INET: wayne@tachyon.com Tachyon Software Consulting |UUCP: uupsi!uupsi6!tachyon!wayne P. O. Box 550937, Dallas TX 75355-0937 |Voice: (214)-553-9760, Fax: -553-0077 ============================================================================= Curly: "I keep tryin' to think, but nuthin' happens!" ================================================================================ Archive-Date: Sat, 15 Jan 1994 02:34:03 CST Sender: LP-Mgr@SHSU.edu From: lwall@netlabs.com (Larry Wall) Reply-To: LitProg@SHSU.edu, lwall@NETLABS.COM Subject: Re: WEB for perl? Message-ID: <1994Jan15.080500.3151@netlabs.com> Date: Sat, 15 Jan 1994 08:05:00 GMT To: LitProg@SHSU.EDU Incidentally, I noticed some literate programmer a while back wishing that Perl supported the #line directives. Guess what. Larry ================================================================================ Archive-Date: Sat, 15 Jan 1994 13:09:21 CST Sender: LP-Mgr@SHSU.edu From: chi@netcom.com (Curt Hagenlocher) Reply-To: LitProg@SHSU.edu, chi@NETCOM.COM Subject: Re: GraphBase for PC's Message-ID: Date: Sat, 15 Jan 1994 18:14:38 GMT To: LitProg@SHSU.EDU Lee Wittenberg writes: >There seems to be another PC-related problem with GB_GRAPH (I just >stumbled over it this morning). It's not a bug, just an >annoyance that can cause very strange run-time errors on PC systems. I discovered this earlier, but as I may have said in another posting, I have had the data recovery week from HELL! >The problem is the |calloc| call in section 13. Knuth is very >careful to make sure that the first argument to |calloc| is less than >2^16, but the second argument is 256, which means that the total >allocated memory may be more than 64K. Microsoft's |calloc| matches >the memory model, so memory will be allocated correctly, but Borland's >won't, so we'll have to change |calloc| to |farcalloc| in the change >file. On the other hand, only ``huge'' pointers can deal with >memory areas > 64K. It seems that only the huge memory model will >do here. The only down-side is that huge pointers are less efficient >than others. On the other hand, they eliminate the problem of the >backward loops (which are disapproved by ANSI, anyway). I have an (unreasonable?) fear of the huge memory model. Has anyone tried this? And does it work? The speed problem you mention is an even bigger nightmare in protected mode (Extended DOS and Windows) and may not even work at all. *Sigh* I guess I've have to hunt up the compiler disks and reinstall to get huge model support so I can test this. Does anyone have any experience persuading one's company to shift development platforms to a "real" environment? :-( -- Curt Hagenlocher chi@netcom.com ================================================================================ Archive-Date: Sat, 15 Jan 1994 18:26:03 CST Sender: LP-Mgr@SHSU.edu Date: Sat, 15 Jan 94 19:25:19 EST From: Lee Wittenberg Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET To: LitProg@shsu.edu, chi@netcom.com Subject: Re: GraphBase for PC's Message-ID: Curt Hagenlocher writes (in response to a suggestion of mine): > I have an (unreasonable?) fear of the huge memory model. Has anyone > tried this? And does it work? I certainly intend to try it myself. I'll let you know. > > The speed problem you mention is an even bigger nightmare in protected > mode (Extended DOS and Windows) and may not even work at all. Argh! I'll just have to try it (keeping my fingers crossed, as Knuth suggests in his installation instructions). > *Sigh* I guess I've have to hunt up the compiler disks and reinstall > to get huge model support so I can test this. Does anyone > have any experience persuading one's company to shift development > platforms to a "real" environment? :-( I had enough trouble convincing the company I worked for last year to try literate programming! :-) \begin{flame} Personally, I don't blame the PC architecture for these problems, but I do blame Microsoft's tendency toward ``creeping featurism,'' and lack of incentive to simplify what they've got. I also blame the compiler writers who don't take the time to provide a consistent interface. Why the Windows compilers can't provide all of the ANSI library calls is beyond me! \end{flame} -- Lee ================================================================================ Archive-Date: Sun, 16 Jan 1994 13:22:49 CST Sender: LP-Mgr@SHSU.edu From: dak@tabaqui.informatik.rwth-aachen.de (David Kastrup) Reply-To: LitProg@SHSU.edu, dak@TABAQUI.INFORMATIK.RWTH-AACHEN.DE Subject: Re: GraphBase for PC's Date: 16 Jan 1994 18:50:37 GMT Message-ID: <2hc29t$in4@urmel.informatik.rwth-aachen.de> MIME-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit To: LitProg@SHSU.EDU chi@netcom.com (Curt Hagenlocher) writes: >Lee Wittenberg writes: >>There seems to be another PC-related problem with GB_GRAPH (I just >>stumbled over it this morning). It's not a bug, just an >>annoyance that can cause very strange run-time errors on PC systems. >I discovered this earlier, but as I may have said in another posting, >I have had the data recovery week from HELL! >>The problem is the |calloc| call in section 13. Knuth is very >>careful to make sure that the first argument to |calloc| is less than >>2^16, but the second argument is 256, which means that the total >>allocated memory may be more than 64K. Microsoft's |calloc| matches >>the memory model, so memory will be allocated correctly, but Borland's >>won't, so we'll have to change |calloc| to |farcalloc| in the change >>file. On the other hand, only ``huge'' pointers can deal with >>memory areas > 64K. It seems that only the huge memory model will >>do here. The only down-side is that huge pointers are less efficient >>than others. On the other hand, they eliminate the problem of the >>backward loops (which are disapproved by ANSI, anyway). >I have an (unreasonable?) fear of the huge memory model. Has anyone >tried this? And does it work? Not in your case, at least under Borland. In the huge model (which is different from large in that it has one static data segment per module, as opposed to per program) pointers are by default still only far, not huge. You will get around only if you declare the problematic cases all by hand as huge. As a note aside: The slackware distribution of Linux can be installed by complete morons by now, and the tools provided in there will beat hell out of DOS whenever memory gets used in large amounts. It comes complete with TeX, eats up (including X11, which is rather nice to have) about 120MB, and will install its own boot manager either on floppy or HD. It will mount and use MSDOS file systems, considerably faster than MSDOS will manage them. Since TeX is a program *not* fitting nicely into 800kByte or less, the TeX of Linux is considerably faster than DOS versions. Plus it will run from inside of your editor, as well as the previewer, all at the same time. Run TeX new, click into the previewer window: voila, same page, new version! Further information in comp.os.linux.announce (as well as ftp sites). Sorry, had to get this off my heart. This setup definitely was very satisfying for me. -- David Kastrup dak@pool.informatik.rwth-aachen.de Tel: +49-241-72419 Fax: +49-241-79502 Goethestr. 20, D-52064 Aachen ================================================================================ Archive-Date: Sun, 16 Jan 1994 13:49:00 CST Sender: LP-Mgr@SHSU.edu From: christib@dhhalden.no (CHRISTIAN BERG) Reply-To: LitProg@SHSU.edu, christib@DHHALDEN.NO Subject: Re: code/info/options for programming an audio cd interface for CD-ROM? Message-ID: Date: Sun, 16 Jan 1994 19:29:46 GMT To: LitProg@SHSU.EDU In article sidic@galadriel.ncssm.edu (Chris Sidi) writes: >From: sidic@galadriel.ncssm.edu (Chris Sidi) >Subject: code/info/options for programming an audio cd interface for CD-ROM? >Date: Wed, 12 Jan 1994 03:23:14 GMT Have you tried the MCI controller ? It follwos the proffsional edition of visual basic if you have a MCI driver installed this control shuld be able to do just what you are loocking for E-mail Christib@sofus.dhhalden.no if it bounces leave out the sofus part ================================================================================ Archive-Date: Mon, 17 Jan 1994 00:07:38 CST Sender: LP-Mgr@SHSU.edu From: chi@netcom.com (Curt Hagenlocher) Reply-To: LitProg@SHSU.edu, chi@NETCOM.COM Subject: Re: GraphBase for PC's Message-ID: Date: Mon, 17 Jan 1994 05:32:43 GMT To: LitProg@SHSU.EDU dak@tabaqui.informatik.rwth-aachen.de (David Kastrup) writes: >chi@netcom.com (Curt Hagenlocher) writes: >>I have an (unreasonable?) fear of the huge memory model. Has anyone >>tried this? And does it work? >Not in your case, at least under Borland. In the huge model (which is >different from large in that it has one static data segment per module, >as opposed to per program) pointers are by default still only far, not >huge. You will get around only if you declare the problematic cases >all by hand as huge. Is this any different from Microsoft C? I've got both... . Actually, my understanding of the huge model was that it dealt only with arrays larger than 64K, and I'm not sure how well this would fit with what Knuth has done to calloc. After a long weekend working, I may have enough spare time to try this tomorrow. >As a note aside: The slackware distribution of Linux can be installed >by complete morons by now, and the tools provided in there will beat >hell out of DOS whenever memory gets used in large amounts. It comes Since you insist, I'd like to put a plug in for FreeBSD which I'm running at home. I don't know how exactly it compares to Linux (it sounds, though like I'm using a bit more disk space), but I've preferred BSDish systems to SYSVish systems for some time. See comp.os.386bsd.* for more info. Unfortunately at work, I'm stuck with the DOG. -- Curt Hagenlocher chi@netcom.com ================================================================================ Archive-Date: Mon, 17 Jan 1994 11:40:13 CST Sender: LP-Mgr@SHSU.edu Message-ID: <9401171739.AA04872@netmail.microsoft.com> From: Eric Landes Reply-To: LitProg@SHSU.edu, ericla@MICROSOFT.COM To: LitProg@SHSU.EDU, LP-Mgr@SHSU.edu Date: Mon, 17 Jan 94 09:05:07 TZ Subject: Re: GraphBase for PC's | | >Not in your case, at least under Borland. In the huge model (which is | >different from large in that it has one static data segment per module, | >as opposed to per program) pointers are by default still only far, not | >huge. You will get around only if you declare the problematic cases | >all by hand as huge. | | Is this any different from Microsoft C? I've got both... . | | Actually, my understanding of the huge model was that it dealt only with | arrays larger than 64K, and I'm not sure how well this would fit | with what Knuth has done to calloc. After a long weekend working, I | may have enough spare time to try this tomorrow. | Essentially there are two differences between huge and large model in Microsoft's compiler. Huge can handle arrays larger than 64K and all pointer arithmetic checks for segment wraparound. Borland defines each memory model slightly differently from what I remember, but it's been years since I've used their compiler. I've used huge model to build Un*x apps for DOS without much difficulty, provided the original authors were kind enough to think about DOS a little bit. If there are problems involving long filenames, I don't try to fix those. I don't have enough time. I'm going to attempt to build SGB under NT when I get the chance. That should be considerably easier. Eric Landes ericla@microsoft.com ================================================================================ Archive-Date: Mon, 17 Jan 1994 18:35:31 CST Sender: LP-Mgr@SHSU.edu From: clarence@orion.cc.andrews.edu (Clarence L. Thomas IV) Reply-To: LitProg@SHSU.edu, clarence@ORION.CC.ANDREWS.EDU Subject: Global Alert For All: Jesus is Coming Soon Date: 17 Jan 1994 18:49:19 -0500 Message-ID: <2hf85v$j66@orion.cc.andrews.edu> To: LitProg@SHSU.EDU The earthquake in Los Angeles, California, the flood in Europe, the seemingly unstoppable war in the former Yugoslavia, the devastating fires in Australia, the flood in the Midwest of the United States of America, the devastating fires near Los Angeles, California, the rapid and appalling increase in violence in cities, towns, villages all over the world, the famines, the diseases, the rapid decline of the family unit, and the destructive earthquake in India (in 1993) are signs that this world's history is coming to a climax. The human race has trampled on God's Constitution, as given in Exodus 20:1-17 (King James Version Bible), and Jesus is coming to set things right. These rapidly accelerating signs are an indication that Jesus is coming soon (Matthew 24). God's Holy Spirit is gradually withdrawing its protection from the earth and the devastating events you see are demonstrations of Satan's power. All those who are not guarded by God are in danger of forever losing eternal life. If you want to know what's about to happen, please study the books of Daniel and Revelation which are located in God's Word, the Bible. They are not sealed or closed books. They can and must be understood by all. Every word in the Bible from Genesis to Revelation is true. The Bible and the Bible only must be your guide. When God's Law (the Constitution for the Universe) is consistently ignored, disregarded, changed, and questioned, He permits certain events to occur to wake us up. I would urge all, wherever you are and regardless of the circumstances, to directly call on Jesus and ask Him to intervene in your life. Jesus who created this planet and every living creature in it and on it, died on the cross, was raised from the dead by God the Father, and is now in Heaven interceding for you. Jesus is the only One who can rescue us from the slavery, misery, and death Satan is causing us. For reference I'm including God's Constitution as given in the King James Version Bible. Please note that when God says the seventh day, he means Sabbath (the 7th day of the week) not Sunday (1st day of the week). Commandment #1: Exodus 20:1-3 (KJV) And God spake all these words, saying, I am the LORD thy God, which have brought thee out of the land of Egypt, out of the house of bondage. Thou shalt have no other gods before me. Commandment #2: Exodus 20:4-6 (KJV) Thou shalt not make unto thee any graven image, or any likeness of any thing that is in heaven above, or that is in the earth beneath, or that is in the water under the earth. And shewing mercy unto thousands of them that love me, and keep my commandments. Commandment #3: Exodus 20:7 (KJV) Thou shalt not take the name of the LORD thy God in vain; for the LORD will not hold him guiltless that taketh his name in vain. Commandment #4: Exodus 20:8-11 (KJV) Remember the sabbath day, to keep it holy. Six days shalt thou labour, and do all thy work: But the seventh day is the sabbath of the LORD thy God: in it thou shalt not do any work, thou, nor thy son, nor thy daughter, thy manservant, nor thy maidservant, nor thy cattle, nor thy stranger that is within thy gates: For in six days the LORD made heaven and earth, the sea, and all that in them is, and rested the seventh day: wherefore the LORD blessed the sabbath day, and hallowed it. Commandment #5: Exodus 20:12 (KJV) Honour thy father and thy mother: that thy days may be long upon the land which the LORD thy God giveth thee. Commandment #6: Exodus 20:13 (KJV) Thou shalt not kill. Commandment #7: Exodus 20:14 (KJV) Thou shalt not commit adultery. Commandment #8: Exodus 20:15 (KJV) Thou shalt not steal. Commandment #9: Exodus 20:16 (KJV) Thou shalt not bear false witness against thy neighbour. Commandment #10: Exodus 20:17 (KJV) Thou shalt not covet thy neighbour's house, thou shalt not covet thy neighbour's wife, nor his manservant, nor his maidservant, nor his ox, nor his ass, nor any thing that is thy neighbour's. I also recommend that the following books be obtained and closely studied: The Great Controversy By Ellen G. White Review and Herald Publishing Association Hagerstown, MD 21740 The Desire of the Ages By Ellen G. White Review and Herald Publishing Association Hagerstown, MD 21740 Patriarchs and Prophets By Ellen G. White Review and Hearld Publishing Association Hagerstown, MD 21740 Daniel and the Revelation By Uriah Smith Review and Herald Publishing Association Hagerstown, MD 21740 ------- Clarence L. Thomas IV Phone: 616-471-6116 E-mail: thomas@redwood.cc.andrews.edu ================================================================================ Archive-Date: Mon, 17 Jan 1994 18:45:11 CST Sender: LP-Mgr@SHSU.edu From: sboyle@wv.MENTORG.COM (Sean Boyle x1542) Reply-To: LitProg@SHSU.edu, sboyle@WV.MENTORG.COM Date: Mon, 17 Jan 94 16:43:48 -0800 Message-ID: <9401180043.AA13751@porkface.mentorg.com> To: LitProg@SHSU.edu, sboyle@wv.MENTORG.COM Subject: nuweb @| and %variable name I am using nuweb to write and document a perl script. I am having trouble getting it to eat varible names with '%' in them. Example @d bletch @{ blah; %blah = foobarzap; blah; %glitch = euragrouch; @| %blah %glitch @} The %blah will show up in this case, but not %glitch. I've so far tried: @| %blah %glitch <-- as above, didn't work @| \%blah \%glitch <-- This didn't work either +------------------------+------------------------------+ | sean_boyle@mentorg.com | Mentor Graphics Corporation | | uunet!mntgfx!sboyle | 8005 S.W. Boeckman Road | | | Wilsonville, OR 97070-7777 | | "Intrinsically lazy, therefore creative" | +------------------------+------------------------------+ ================================================================================ Archive-Date: Tue, 18 Jan 1994 11:31:22 CST Sender: LP-Mgr@SHSU.edu From: pdelaney@world.std.com (Peter M Delaney) Reply-To: LitProg@SHSU.edu, pdelaney@WORLD.STD.COM Subject: Equation of two intersecting lines Message-ID: Date: Tue, 18 Jan 1994 16:39:02 GMT To: LitProg@SHSU.EDU HELP NEEDED: Equation determining the intersecting point for two straight lines. |<------Radius ------>| | | | | | | 1 P 2 | --------------+--------|------+............... \ . \ . \ . Known Values \ . -------------------------- \ . Points 1,2,3,P, and Radius \ . \. <-------- Intersection .\ of 2 lines . \ . \ . \ . \ \ + 3 My problem is to find and equation that will give the Intersecting points of these two lines. I know Points 1,2,3 and points P. I also know the Radius which will intersect the lines. I have tried to derive the equation for the Intersection point, but my results are not correct. Can anyone tell me where I could find a book that would have the equation of two straight lines. Thanks in advance for your help. Peter Delaney ================================================================================ Archive-Date: Tue, 18 Jan 1994 12:26:03 CST Sender: LP-Mgr@SHSU.edu From: pjp@sloth.mlb.semi.harris.com (Pat J. Pinchera) Reply-To: LitProg@SHSU.edu, pjp@SLOTH.MLB.SEMI.HARRIS.COM Subject: Literate Programming Bibliography Question Date: Tue, 18 Jan 1994 17:15:26 GMT Message-ID: <1994Jan18.171526.23849@mlb.semi.harris.com> To: LitProg@SHSU.EDU I recently obtained the Literate Programming Bibliography via anonymous ftp. I just have one question: what format is this file in, and where can I get the necessary s/w to read or translate this file? If you know of a FAQ or ftp site to get the files, (I assume Tex formatter or something), just tell me that. I am very interested in using Literate Programming to document my C++ class libraries. Thanks. Pat Pinchera pjp@sloth.mlb.semi.harris.com -- Patrick Pinchera pjp@mlb.semi.harris.com ICS "If I knew art smelled this good, I would've come here years Melbourne, FL ago." Melanie Griffith as Billie Dawn in _Born_Yesterday_ ================================================================================ Archive-Date: Tue, 18 Jan 1994 13:33:20 CST Sender: LP-Mgr@SHSU.edu From: cgra@se.alcbel.be (Chris Gray) Subject: Re: Equation of two intersecting lines Message-ID: <2489@se.alcbel.be> Date: 18 Jan 94 17:37:26 GMT Reply-To: LitProg@SHSU.edu, cgra@se.alcbel.be To: LitProg@SHSU.EDU Uh? __________________________________________________________________________ Chris Gray cgra@se.alcbel.be Compu$erve: 100065.2102 ================================================================================ Archive-Date: Tue, 18 Jan 1994 14:41:21 CST Sender: LP-Mgr@SHSU.edu From: carroll@nori.cis.udel.edu (Mark C. Carroll) Reply-To: LitProg@SHSU.edu, carroll@NORI.CIS.UDEL.EDU Subject: Importance of indexing? Date: 18 Jan 1994 19:55:56 GMT Message-ID: <2hhesc$qv4@louie.udel.edu> To: LitProg@SHSU.EDU Greetings! I'm currently working on an HTML based literate programming tool. (For those who don't know, HTML is an SGML based markup language for hypertext documents. HTML can be read by the Mosaic tool from NCSA, or with a variety of other tools including an emacs mode.) I've got the tool working, but I don't do any indexing of variable definitions. I haven't implemented that, because I *never* look at the things when I read a literate program. (They wouldn't be too hard to add, but the addition of the index would involve some rather un-SGML like contortions, which I've been trying to avoid.) So, at last, my question is: how important do other, more experienced literate programmers find indentifier indices? (For interested persons: Yes, I do plan to release this tool eventually. However, it's currently rather ugly, and needs serious work before anyone else sees it. I've currently got a version that's just capable of bootstrapping itself. No one but me gets to see it until the code is considerably cleaned up.) -- [ Mark Craig Carroll ] You say you know no tricks, have no talents - [ U of Delaware, CIS Dept ] Isn't everyone supposed to have their own? [ PGP key available, ] Yes, but few are obvious. Few draw notice to those [ finger carroll@udel.edu ] who posess them, like flags waving themselves. ================================================================================ Archive-Date: Tue, 18 Jan 1994 16:30:20 CST Sender: LP-Mgr@SHSU.edu From: "John Lacey" Reply-To: LitProg@SHSU.edu, johnl@CS.INDIANA.EDU Subject: Re: Importance of indexing? Message-ID: <1994Jan18.160107.20726@news.cs.indiana.edu> Date: Tue, 18 Jan 1994 16:01:02 -0500 To: LitProg@SHSU.EDU carroll@nori.cis.udel.edu (Mark C. Carroll) writes: > I've got the tool working, but I don't do any indexing of > variable definitions. I haven't implemented that, because I > *never* look at the things when I read a literate program. > [...]. > > So, at last, my question is: how important do other, more > experienced literate programmers find indentifier indices? I don't find the index useful at all, *UNLESS* it is on each page, as in the published TeX and METAFONT programs. In that case, i find it indispensable. (I have a love/hate relationship with the programs themselves, but i will not deny either their readability or the skills of the author.) IMHO, WEB and it's ilk are useless without indexing. If you remove the features that simply cater to a deficient language, those which can be handled with sed or awk one-liners (OK, maybe several-liners), and those that vgrind/tgrind handle, you are left with just indexing (and, admittedly, the ability to use and typeset really long procedure names in the local vernacular). John L ================================================================================ Archive-Date: Tue, 18 Jan 1994 16:50:02 CST Sender: LP-Mgr@SHSU.edu From: przemek@rrdbartok.nist.gov (Przemek Klosowski) Reply-To: LitProg@SHSU.edu, przemek@RRDBARTOK.NIST.GOV Subject: Re: nuweb @| and %variable name Message-ID: Date: Tue, 18 Jan 1994 21:49:21 GMT To: LitProg@SHSU.EDU In article <19363906@MVB.SAIC.COM> sboyle@wv.MENTORG.COM (Sean Boyle x1542) writes: I am using nuweb to write and document a perl script. I am having trouble getting it to eat varible names with '%' in them. Example @d bletch @{ blah; %blah = foobarzap; blah; %glitch = euragrouch; @| %blah %glitch @} I use @| blah glitch @}, because I want the names in the index in alphabetical sequence rather than lumped under $ or % or @. I wish there was an option to provide one name to sort the index entries by, and another name to be formatted for printing, e.g. @| @I{blah}{\%blah} @} This is syntactically awkward, but you can see the general idea. I suggested as much to Preston, and he answered that he is busy but might consider it for a future version of nuweb. -- przemek klosowski (przemek@rrdstrad.nist.gov) Reactor Division (bldg. 235), E111 National Institute of Standards and Technology Gaithersburg, MD 20899, USA (301) 975 6249 tel (301) 921 9847 fax ================================================================================ Archive-Date: Tue, 18 Jan 1994 17:15:10 CST Sender: LP-Mgr@SHSU.edu Date: Tue, 18 Jan 94 18:11:58 EST From: Lee Wittenberg Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET To: LitProg@shsu.edu, pjp@sloth.mlb.semi.harris.com Subject: Re: Literate Programming Bibliography Question Message-ID: Pat Pinchera writes: > I recently obtained the Literate Programming Bibliography > via anonymous ftp. I just have one question: what format is > this file in, and where can I get the necessary s/w to read or > translate this file? If you know of a FAQ or ftp site to get the > files, (I assume Tex formatter or something), just tell me that. > I am very interested in using Literate Programming to document > my C++ class libraries. Thanks. It's in BibTeX format. BibTeX is usually distributed as part of the LaTeX package. If you already have access to TeX, you probably already have access to BibTeX. If not, you will probably want to get a copy of TeX from the CTAN archives (probably the same place you got the bibliography). Which TeX implementation you choose will depend on the operating system you're using. If it's DOS or OS/2, I can highly recommend emTeX, which definitely comes with BibTeX. -- Lee leew@pilot.njin.net ================================================================================ Archive-Date: Tue, 18 Jan 1994 17:23:13 CST Sender: LP-Mgr@SHSU.edu Date: Tue, 18 Jan 94 18:22:35 EST From: Lee Wittenberg Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET To: LitProg@shsu.edu, carroll@nori.cis.udel.edu Subject: Re: Importance of indexing? Message-ID: Mark Craig Carroll asks: > So, at last, my question is: how important do other, more experienced > literate programmers find indentifier indices? I find them invaluable. Not for my own code -- I usually know where things are, but when I'm reading someone else's web, I find myself constantly referring to the indentifier index: ``How and where is that d---ed variable (or function) declared?''. "The Stanford GraphBase" would be an order of magnitude harder to get through if the identifiers weren't indexed, and I don't think I ever would have gotten CWEB 2.4 working on my PC if not for the identifier index. > (For interested persons: Yes, I do plan to release this tool > eventually. However, it's currently rather ugly, and needs serious > work before anyone else sees it. I've currently got a version that's > just capable of bootstrapping itself. No one but me gets to see it > until the code is considerably cleaned up.) I know the feeling. -- Lee leew@pilot.njin.net ================================================================================ Archive-Date: Tue, 18 Jan 1994 17:27:06 CST Sender: LP-Mgr@SHSU.edu From: mauer@mcs.anl.gov (Andrew Mauer) Reply-To: LitProg@SHSU.edu, mauer@MCS.ANL.GOV Subject: Re: Importance of indexing? Message-ID: Date: Tue, 18 Jan 1994 21:20:57 GMT To: LitProg@SHSU.EDU >>>>> On 18 Jan 1994 19:55:56 GMT, carroll@nori.cis.udel.edu (Mark C. Carroll) said: Mark> So, at last, my question is: how important do other, more experienced Mark> literate programmers find indentifier indices? I certainly DO NOT QUALIFY ... but I have "tangled" with noweb (as my rather questionable posts to this group have attested), and I have found identifier indices *very very nice*. If one is trying to change just a part of a program, easy access to the "information flow" allows you to tweak it without understanding the whole structure. This greatly increases the ease of hacking (and presumably maintenance). :-) /Andrew/ -- /Andrew Mauer/ mauer@mcs.anl.gov ================================================================================ Archive-Date: Tue, 18 Jan 1994 17:27:10 CST Sender: LP-Mgr@SHSU.edu From: preston@dawn.cs.rice.edu (Preston Briggs) Reply-To: LitProg@SHSU.edu, preston@DAWN.CS.RICE.EDU Subject: Re: nuweb @| and %variable name Message-ID: Date: Tue, 18 Jan 1994 17:57:03 GMT To: LitProg@SHSU.EDU sboyle@wv.MENTORG.COM (Sean Boyle x1542) writes: >I am using nuweb to write and document a perl script. I am having >trouble getting it to eat varible names with '%' in them. >Example > >@d bletch >@{ >blah; >%blah = foobarzap; >blah; >%glitch = euragrouch; >@| %blah %glitch @} > >The %blah will show up in this case, but not %glitch. I tried several examples of this sort of thing, including the example given above, and they all worked fine. >I've so far >tried: > @| %blah %glitch <-- as above, didn't work > @| \%blah \%glitch <-- This didn't work The 2nd version shouldn't work. Or rather, it'll cause the indexer to look for exact matches to \%blah and \%glitch rather than %blah and %glitch. Is it possible you have a typo? For example, @d bletch @{ blah; %blah = foobarzap; blah; %glitch = euragrouch; @| %blah %glich @} ^there's a 't' missing here would cause the indexer to look for occurences of "%glich". If none are found, no entry will be created in the index for %glich (or, of course, for %glitch). Otherwise, if you could mail me a file that exhibits the problem, I'll be glad to check it out. Preston Briggs ================================================================================ Archive-Date: Tue, 18 Jan 1994 19:08:18 CST Sender: LP-Mgr@SHSU.edu Date: Tue, 18 Jan 94 19:55:12 EST From: Lee Wittenberg Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET To: LitProg@shsu.edu Subject: DOS noweb testers needed Message-ID: Wanted: alpha/beta/whatever-Greek-letter-you-like testers for a DOS version of noweb 2.5a. If you're interested, please contact me directly. Thanks in advance. -- Lee Wittenberg leew@pilot.njin.net ================================================================================ Archive-Date: Wed, 19 Jan 1994 05:38:08 CST Sender: LP-Mgr@SHSU.edu From: shf@netcom.com (Stuart Ferguson) Reply-To: LitProg@SHSU.edu, shf@NETCOM.COM Subject: Re: Importance of indexing? Message-ID: Date: Wed, 19 Jan 1994 08:39:32 GMT To: LitProg@SHSU.EDU +-- carroll@nori.cis.udel.edu (Mark C. Carroll) writes: | I'm currently working on an HTML based literate programming tool. [...] | I've got the tool working, but I don't do any indexing of variable | definitions. I haven't implemented that, because I *never* look at the | things when I read a literate program. (They wouldn't be too hard to | add, but the addition of the index would involve some rather un-SGML | like contortions, which I've been trying to avoid.) Just a thought -- but doesn't HTML support a form of hypertext? If so, why not have the symbol references be linked back to their definition site? -- Stuart Ferguson (shf@netcom.com) "Jupiter -- America's dairyland!" Eight days to Midnight. ================================================================================ Archive-Date: Wed, 19 Jan 1994 15:49:00 CST Sender: LP-Mgr@SHSU.edu Date: Wed, 19 Jan 94 19:36:04 GMT Message-ID: <20689@apusapus.demon.co.uk> From: Trevor Jenkins Reply-To: LitProg@SHSU.edu, tfj@APUSAPUS.DEMON.CO.UK To: LitProg@shsu.edu CC: carroll@nori.cis.udel.edu, tfj@apusapus.demon.co.uk Subject: Re: Importance of indexing? In message <2hhesc$qv4@louie.udel.edu> you write: > So, at last, my question is: how important do other, more experienced > literate programmers find indentifier indices? I rarely use the full indices for programs that I've written. However, when reading DEK's source of TeX and metafont I find the mini-indices invaluable. Regards, Trevor. --------------------------------------------------------------------------- Trevor Jenkins Re: "deemed!" 134 Frankland Rd, Croxley Green, RICKMANSWORTH, WD3 3AU, England email: tfj@apusapus.demon.co.uk phone: +44 (0)923 776436 radio: G6AJG "We need bigger and better books", Jimmy Tingle (Damned in the USA) ================================================================================ Archive-Date: Wed, 19 Jan 1994 17:14:45 CST Sender: LP-Mgr@SHSU.edu From: carroll@nori.cis.udel.edu (Mark C. Carroll) Reply-To: LitProg@SHSU.edu, carroll@NORI.CIS.UDEL.EDU Subject: Request for comments: literate hypertext indices Date: 19 Jan 1994 21:56:03 GMT Message-ID: <2hka9j$rs9@louie.udel.edu> To: LitProg@SHSU.EDU Greetings! The response to my earlier question about the importance of indexing has been overwhelmingly in favor of including indices. A large number of those have requested multiple indices, rather than a single indentifier index at the end of the document. In response to this, I've come up with a tentative idea for how to handle indices, which I'd like to open up for comments. First, let me introduce the syntax of my system, which should allow me to make a little more sense when I explain the indexing idea. Chunks in my system are described using an SGML style begin/end tag. The begin tag takes two fields: a mandatory name field, and an optional file field. If the file field is present, the chunk is a root chunk, and will be tangled to the file specified in the field argument. Chunk references are simple tags with a ref field, naming the chunk. Eventually, this reference will be allowed to link to another file, but my tangler doesn't handle that yet. An example chunk with references: #include main() { for (i=0;i<10;i++) } Now, the indexing proposal that I've come up with fits in with this syntax. The chunk opener will take an extra field, specifying the index into which definitions from this chunk will be inserted. Then, definitions are declared using a definition tag around the identifiers to be indexed. So: #include main() { int i; for (i=0;i<10;i++) } The definition tag will have an optional field naming an index to insert the identifier into if it is not the default index for the chunk. The weaver will generate an index file for each specified index. The file author can provide links into this file from wherever it is appropriate to reference an index. I'm inclined towards only indexing the definitions of an identifier, and not uses. But I could probably be convinced to add use indexing as an option, if enough people prod me. Does this seem like a reasonable indexing method for a hypertext web? -- || Mark Craig Carroll: || "I'm not dumb, || CIS Grad, U of Delaware || I just have a command of thoroughly || PGP key available by finger || useless information." || carroll@udel.edu || -Calvin ================================================================================ Archive-Date: Wed, 19 Jan 1994 19:25:17 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: <9401200120.AA15662@ra.pad.otc.com.au> Subject: Re: Request for comments: literate hypertext indices To: LitProg@SHSU.edu, carroll@nori.cis.udel.edu Date: Thu, 20 Jan 1994 12:20:04 +1100 (AEST) MIME-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit Mark C. Carroll... > > First, let me introduce the syntax of my system, which should allow me > to make a little more sense when I explain the indexing idea. > I may have this wrong, but are you developing a WEB system that uses a modified SMGL/HTML as its language? As a personal observation, I find the syntax you are preposing a little cumbersome compared to nu/noweb. Would it not be better to use one of these "standard" tools and re-target the output to HTML? If you made this a switch, then you would have the benefit of being able to produce a hardcopy in LaTeX and have a hypertext version in HTML. I had a quick look at doing this in nuweb, but Preston designed the output sections with LaTeX in mind. Maybe noweb would be an "easier" target. -- mark. (probertm@nms.otc.com.au) ph: (02) 339 3953 fax: (02) 339 3688 ================================================================================ Archive-Date: Wed, 19 Jan 1994 19:34:42 CST Sender: LP-Mgr@SHSU.edu From: jkorver@iastate.edu (Juliana B Korver) Reply-To: LitProg@SHSU.edu, jkorver@IASTATE.EDU Subject: C, C++ questions Date: 20 Jan 94 00:38:24 GMT Message-ID: Keywords: C, C++ To: LitProg@SHSU.EDU I am looking for answers to the following please. What are the major flaws with C (or maybe not so major) Why is C (or C++) not always the best language for all kinds of software Why is more research in programming languages still needed ??? Please email me any responses. Thanks in advance. Juliana korver@cs.iastate.edu -- ================================================================================ Archive-Date: Wed, 19 Jan 1994 19:34:58 CST Sender: LP-Mgr@SHSU.edu From: preston@dawn.cs.rice.edu (Preston Briggs) Reply-To: LitProg@SHSU.edu, preston@DAWN.CS.RICE.EDU Subject: Re: Importance of indexing? Message-ID: Date: Wed, 19 Jan 1994 17:03:17 GMT To: LitProg@SHSU.EDU carroll@nori.cis.udel.edu (Mark C. Carroll) writes: >I've got the tool working, but I don't do any indexing of variable >definitions. I haven't implemented that, because I *never* look at the >things when I read a literate program. >my question is: how important do other, more experienced >literate programmers find indentifier indices? I don't use indices so much for my own code (though I'm finding them more useful as my code gets older); however, we (meaning my group) use them quite a lot in reviewing each others code. In olden times, we wanted a terminal handy when we did walkthroughs, so we could find places where a variables was declared or initialized. It was such a typical walkthrough question to suddenly ask: Hey, is this thing initialized to NULL? (or zero or "blocks" or "blocks - 1" or initialized at all) Preston Briggs ================================================================================ Archive-Date: Thu, 20 Jan 1994 00:10:00 CST Sender: LP-Mgr@SHSU.edu From: bart@thrain.anu.edu.au (Bart Childs) Reply-To: LitProg@SHSU.edu, bart@THRAIN.ANU.EDU.AU Subject: Re: Usefulness of Indexes Date: 20 Jan 1994 05:01:44 GMT Message-ID: <2hl37o$7gc@manuel.anu.edu.au> Keywords: indexes To: LitProg@SHSU.EDU It is easy to lose sight of the usefullness of indexes if all you do is write new code. They are invaluable. I ported TeX and MF to several machines before volume B of C&T was available where the mini-indices were on the pages you look at. Still, they were invaluable although the mini-indices were there on the last port I did. That too is a big help. Have you ever taken a course from a textbook being developed? I have not but have taught one several semesters in that situation (no I am not the author either) and it is pure torture for the student. We often hear that 60 to 80% of the cost of software in its lifetime is maintenance. If that is true, then every help we can give the maintenance programmer should lead to economy, profit, or whatever drives your system. I think the aids of keywords, programmer supplied names, ... in the formatting of the language specific WEBs and their indices (or indexes) are two great helps for the future maintainer of my software. The structure and integration of documentation are also valuable..... Bart Childs really bart@cs.tamu.edu on leave in the land of Australia ================================================================================ Archive-Date: Thu, 20 Jan 1994 03:47:22 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: Request for comments: literate hypertext indices Date: Thu, 20 Jan 1994 08:45:44 GMT Message-ID: <7590555441848@inet.uni-c.dk> To: LitProg@SHSU.EDU On 19 Jan 1994 21:56:03 GMT, Mark C. Carroll wrote: >Greetings! > >The response to my earlier question about the importance of indexing >has been overwhelmingly in favor of including indices. A large number >of those have requested multiple indices, rather than a single >indentifier index at the end of the document. I second the use of multiple indices --- in principle. The problem with multiple indices is that they are so hard to get right the first time (just like ordinary indices). All to often you end up with a lot of unnessesary identifiers; I speak from experience and that was with just one index :-( >In response to this, I've come up with a tentative idea for how to >handle indices, which I'd like to open up for comments. [...] I like the idea (if only I could control myself with such a tool :-) >I'm inclined towards only indexing the definitions of an identifier, >and not uses. But I could probably be convinced to add use indexing as >an option, if enough people prod me. Unless you're doing object-orientated programming, I'd say you have to provide some indexing of identifiers in interesting places. BTW: OOP adds to your basic indexing of definitions and I guess it breaks your hypertext system as it is (I hope not) If we have: for(i=0;idraw(); the Frame class doesn't define the draw method, but it's inherited from the GraphicBase class. I would like to tell me reader that Frame::draw is intended to be called (conceptually good idea) but due to subclassing the draw method in GraphicsBase is called. Opinions, anyone?? >Does this seem like a reasonable indexing method for a hypertext web? Yes, if the programmer doesn't get carried away, thus making the resulting web more or less unreadeble. If I was using (i.e. reading) a hypertext web, I would expect to be able to pick on one identifier and from there be able to see: 1. Where it's defined. 2. Interesting places where it's used. --- this is where the fun part of indexing starts :-) 3. All places where it's used. /Jacob -- Jacob Nielsen Email: jacojn@inet.uni-c.dk (my private account) or bc898574@bbar.dth.dk (my account at the university) ================================================================================ Archive-Date: Thu, 20 Jan 1994 03:52:32 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: HTML WEB Date: Thu, 20 Jan 1994 09:03:17 +0000 Hello, Mark.Probert writes > I may have this wrong, but are you developing a WEB system that uses a > modified SMGL/HTML as its language? > > As a personal observation, I find the syntax you are > preposing a little cumbersome compared to nu/noweb. Would it not be > better to use one of these "standard" tools and re-target the output > to HTML? If you made this a switch, then you would have the benefit of > being able to produce a hardcopy in LaTeX and have a hypertext > version in HTML. I had a quick look at doing this in nuweb, but > Preston designed the output sections with LaTeX in mind. Maybe noweb > would be an "easier" target. I found a small program that converts TeX/LaTeX to RTF/HTML (and some others) called tex2rtf. It seems to work quite well I think (taking account of styles etc.) but I have not really used it much. Because HTML is relatively simple, it does not have to do a lot of work to produce a reasonable output. This might be used to take nu/noweb output and hypertext it? I had started investigating this myself but I cannot get a language independent WEB for MS-DOS (running in windows, etc. - except WinWordWEB). You could display full literate programmes on WWW and encourage those who do not have TeX/LaTeX/WEB to read the results. Stephen Mc Kearney ================================================================================ Archive-Date: Thu, 20 Jan 1994 09:26:29 CST Sender: LP-Mgr@SHSU.edu Date: Thu, 20 Jan 94 10:24:11 EST From: aed@arbortext.com Reply-To: LitProg@SHSU.edu, aed@ARBORTEXT.COM Message-ID: <9401201524.AA18726@ironwood.arbortext.com> To: LitProg@SHSU.edu, Mark.Probert@NMS.OTC.COM.AU CC: carroll@nori.cis.udel.edu Subject: Re: Request for comments: literate hypertext indices Mark C. Carroll... > > First, let me introduce the syntax of my system, which should allow me > to make a little more sense when I explain the indexing idea. > Mark Probert (Mark.Probert@nms.otc.com.au) writes: I may have this wrong, but are you developing a WEB system that uses a modified SMGL/HTML as its language? As a personal observation, I find the syntax you are preposing a little cumbersome compared to nu/noweb. Would it not be better to use one of these "standard" tools and re-target the output to HTML? If you made this a switch, then you would have the benefit of being able to produce a hardcopy in LaTeX and have a hypertext version in HTML.... Agreed, however, the syntax proposed by Mark Carroll would not be awkward in a native SGML editor where markup does not appear as a sequence of ascii characters. In such an editor Mark's system would be an very good way to write literate code. Using noweb or nuweb would be awkward in comparison because the advantages of SGML, for example the separation of content (the code) from structure (the noweb or nuweb directives), would not be applied. As for the need for an index, it may not be necessary for online use with an appropriate editor, but in my limited experience with literate programming I found it useful for reading printed code. -- Andrew Dobrowolski (aed@arbortext.com) ================================================================================ Archive-Date: Thu, 20 Jan 1994 09:29:52 CST Sender: LP-Mgr@SHSU.edu Date: Thu, 20 Jan 94 10:28:35 EST From: Lee Wittenberg Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET To: LitProg@shsu.edu, carroll@nori.cis.udel.edu Subject: Re: Request for comments: literate hypertext indices Message-ID: Mark Craig Carrol has presented a tentative syntax for his SGML-based LP system, requesting comments on the syntax. I don't know SGML, but the proposed syntax seems like a fairly straightforward extension of what he's already got, which (IMHO) is all to the good. The simpler the syntax the better (that's why I like noweb). > I'm inclined towards only indexing the definitions of an identifier, > and not uses. But I could probably be convinced to add use indexing as > an option, if enough people prod me. Indexing uses is vital if you're maintaining a program you didn't write! We can't count on the people who come before us to use what we consider a completely modular design :-(, so there is no guarantee that identifer use is encapulated in any meaningful way (encapsulation itself causes some interesting problems in webs, but that's another story). The best way to find out the consequences of messing with a variable or function is the check in the index to find all the places where the appropriate identifier is used (it helps to find bugs, too). Knuth's mini-indices are nice, but they can't help here. noweb's mini-indices include pointers to where identifiers are used, but I still find myself relying mostly on the main index (of course, this may simply be force of habit). I should mention that I am one of those people who prefers to spend as much time as possible off of the computer. I therefore prefer to work from a printed, woven listing. This certainly colors my opinions. Indices are not needed at all when one sits at the computer with the source (that's what grep is for). -- Lee leew@pilot.njin.net ================================================================================ Archive-Date: Thu, 20 Jan 1994 09:44:14 CST Sender: LP-Mgr@SHSU.edu Date: Thu, 20 Jan 94 10:43:46 EST From: Lee Wittenberg Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET To: LitProg@shsu.edu, bart@thrain.anu.edu.au Subject: Re: Usefulness of Indexes Message-ID: Bart Childs writes: > Have you ever taken a course from a textbook being developed? > I have not but have taught one several semesters in that > situation (no I am not the author either) and it is > pure torture for the student. I don't remember it being so bad. On the other hand, it was in a small seminar rather than a large lecture. That may have made the difference. > We often hear that 60 to 80% of the cost of software in its > lifetime is maintenance. If that is true, then every help > we can give the maintenance programmer should lead to > economy, profit, or whatever drives your system. I think > the aids of keywords, programmer supplied names, ... in the > formatting of the language specific WEBs and their indices > (or indexes) are two great helps for the future maintainer > of my software. Hear, hear! > The structure and integration of documentation are also > valuable..... Ditto, ditto! -- Lee leew@pilot.njin.net ================================================================================ Archive-Date: Thu, 20 Jan 1994 12:34:27 CST Sender: LP-Mgr@SHSU.edu From: heaney@delft.sgp.slb.com (Steve Heaney) Subject: SGML and software development Date: 20 Jan 1994 16:05:08 GMT Message-ID: <2hma3k$lo6@gorgon.gatwick.sgp.slb.com> Reply-To: LitProg@SHSU.edu, heaney@delft.sgp.slb.com Keywords: SGML software literate process To: LitProg@SHSU.EDU An few thoughts that I'd appreciate some input on please. It occurs to me that SGML (the Standard Generalised Markup Language) provides many possibilities for supporting a software development environment. Because SGML provides the means of defining and verifying the content and structure of a "document" it offers, for example, the potential for coupling the documentation produced by software process (requirements, spec, design docs) with program source and beyond to maintenance manuals. This could take the form of a literate programming tool such as Web which combines source and documentation into one file. Alternatively it could form the basis of a more comprehensive CASE environment. Once you start thinking about it, many opportutities to exploit SGML occur. How about: - being better able to track requirements through specification, design and implementation. - supporting hypertext in your "source code". - generating or validating interfaces directly from your documentation. - formal validation of a program against assertions in the documentation. - defining a high level programming language which can be transformed into a number of target languages. Of course, none of these suggestions is immediately provided as an intrinsic feature of SGML - but SGML has the potential to provide an extensible, vendor neutral, language independent environment for software development with a few carefully thought out DTD's and the use of some of the software available on the net. Maybe someone has tried some of this already. I would be very interested if anyone has DTD's or DTD fragments for program specification or design, especially if these have been coupled with tools for generating or validating the resultant source code. Steve. ------------------------------------------------------------------------ Steven Heaney Schlumberger Geco-Prakla Schlumberger House Gatwick Airport UK Internet: heaney@gatwick.sgp.slb.com ------------------------------------------------------------------------ ================================================================================ Archive-Date: Thu, 20 Jan 1994 13:01:27 CST Sender: LP-Mgr@SHSU.edu Date: Thu, 20 Jan 94 11:00:41 PST From: pete@sei.com (Peter Johnson) Reply-To: LitProg@SHSU.edu, pete@SEI.COM Message-ID: <9401201900.AA18748@seismic.sei.com> To: LitProg@SHSU.edu, Mark.Probert@NMS.OTC.COM.AU Subject: Re: Request for comments: literate hypertext indices References: <2hka9j$rs9@louie.udel.edu> <9401200120.AA15662@ra.pad.otc.com.au> Mark Probert writes: > Mark C. Carroll... > > > > First, let me introduce the syntax of my system, which should allow me > > to make a little more sense when I explain the indexing idea. > > > > As a personal observation, I find the syntax you are > preposing a little cumbersome compared to nu/noweb. Would it not be > better to use one of these "standard" tools and re-target the output > to HTML? To someone familiar with SGML, this is probably amusing. What we do when we write literate programs is "markup" the text (code). Since SGML is a standard for text markup (ISO8879) I would tend to call nuweb and noweb the nonstandard tools. > If you made this a switch, then you would have the benefit of > being able to produce a hardcopy in LaTeX and have a hypertext > version in HTML. I had a quick look at doing this in nuweb, but > Preston designed the output sections with LaTeX in mind. Maybe noweb > would be an "easier" target. I have been playing with literate programming and generating HTML output. I have looked at both ways, and find using SGML as a starting point to be preferable. One nice thing about using SGML for literate programming is that you can develop some simple tools, and then incorporate literate programming into any type of document that you like. For example, if you wanted HTML output, you could come up with a new document type for HTML which has literate programming extensions. Then with minimal fuss you can convert this into HTML using an existing SGML parsing tool. This is what I have been playing with. On the other hand, if you wanted to output TeX, you could use the same literate programming extensions with sgml documents designed to generate TeX. As for syntax being complicated. I have to agree, but if you use an SGML parser, you can use a number of SGML markup minimization techniques, and have the parser normalize the output. #include main() { int i; for (i=0;i<10;i++) } becomes #include <stdio.h> Of course, there are also ways of getting around specifying the file and index attributes of the chunk. -Pete -- Peter Johnson Silicon Engineering, Inc. 269 Mt. Hermon Road, Suite 207 (408) 438-5331 x 111 Scotts Valley, CA 95066 pete@sei.com ================================================================================ Archive-Date: Thu, 20 Jan 1994 15:19:58 CST Sender: LP-Mgr@SHSU.edu Date: Thu, 20 Jan 94 14:45:55 CST From: "C. M. Sperberg-McQueen" Reply-To: LitProg@SHSU.edu, U35395%UICVM.BITNET@SHSU.EDU Subject: Re: SGML and software development To: LitProg@SHSU.edu, heaney@delft.sgp.slb.com On 20 Jan 1994 16:05:08 GMT said: > Maybe someone has tried some of this already. I would be very > interested if anyone has DTD's or DTD fragments for program > specification or design, especially if these have been coupled > with tools for generating or validating the resultant source > code. There is an SGML DTD fragment for the specification language Z, which is part of the Z Interchange Format (contact John.Nicholls@prg.oxford.ac.uk for more information) and there are a few people, myself included, who have thought and sometimes talked about writing a DTD or DTD fragment for use in an SGML-based literate programming system. But I don't know of any finished systems for general programming. (I do use a finished system, inspired by Web, to document SGML document type declarations. But the next revision will, I think, be much more like nuweb and noweb, and the scrap mechanism will look a lot like what Mark Carroll describes, with the addition of a 'lang' attribute to identify the language of a scrap, so that language-specific routines can reliably be invoked, to handle indexing or pretty-printing or what have you.) It is not necessarily the case, of course, that the entire evolution of a system, from specification to code, should be documented in a single document. But of course it would be handy to do specifications documents, user manuals, and literate programming using the same document processing tools. Those who use TeX or LaTeX for everything can already do this; those of us who prefer SGML still need the tools. The first cut, of course, can be a simple translation from the SGML tag set into the existing web system of one's choice. -C. M. Sperberg-McQueen ACH / ACL / ALLC Text Encoding Initiative University of Illinois at Chicago u35395@uicvm.uic.edu / u35395@uicvm ================================================================================ Archive-Date: Thu, 20 Jan 1994 16:24:02 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: <9401202215.AA20382@ra.pad.otc.com.au> Subject: Re: Request for comments: literate hypertext indices To: LitProg@SHSU.edu, aed@arbortext.com Date: Fri, 21 Jan 1994 09:15:47 +1100 (AEST) MIME-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit aed@arbortext.com... > > Agreed, however, the syntax proposed by Mark Carroll would not be > awkward in a native SGML editor where markup does not appear as a > sequence of ascii characters. In such an editor Mark's system > would be an very good way to write literate code. > Are native SGML editors freely available? I am using HTML-mode in emacs writing for Mosiac and don't have a full SGML "environment". So, for me, a hypertext document is a ASCII document full of commands. -- mark. (probertm@nms.otc.com.au) ph: (02) 339 3953 fax: (02) 339 3688 ================================================================================ Archive-Date: Thu, 20 Jan 1994 16:30:39 CST Sender: LP-Mgr@SHSU.edu From: mauer@mcs.anl.gov (Andrew Mauer) Reply-To: LitProg@SHSU.edu, mauer@MCS.ANL.GOV Subject: Indexing in Noweb Message-ID: Date: Thu, 20 Jan 1994 21:01:37 GMT To: LitProg@SHSU.EDU All of this talk of indexing has made me wonder... I have tried to make a use/def index in noweb, largely successfully. However, I am curious why the mini-indices do not include references to other definitions. (In other words, if you have an indentifier %def-ined in two places and used nowhere else, the mini-indices in both places will say "never used".) Is this a feature? I can see it could be useful in some contexts, but sort of bothers me because it does not really convey what is happening to the identifier in the rest of the program. /Andrew/ -- /Andrew Mauer/ mauer@mcs.anl.gov ================================================================================ Archive-Date: Thu, 20 Jan 1994 17:09:01 CST Sender: LP-Mgr@SHSU.edu Date: Thu, 20 Jan 94 18:05:45 EST From: aed@arbortext.com Reply-To: LitProg@SHSU.edu, aed@ARBORTEXT.COM Message-ID: <9401202305.AA23452@ironwood.arbortext.com> To: LitProg@SHSU.edu, Mark.Probert@NMS.OTC.COM.AU Subject: Re: Request for comments: literate hypertext indices Mark.Probert@nms.otc.com.au (Mark Probert) writes... aed@arbortext.com... > > Agreed, however, the syntax proposed by Mark Carroll would not be > awkward in a native SGML editor where markup does not appear as a > sequence of ascii characters. In such an editor Mark's system > would be an very good way to write literate code. > Are native SGML editors freely available? I am using HTML-mode in emacs writing for Mosiac and don't have a full SGML "environment". So, for me, a hypertext document is a ASCII document full of commands. I don't know of any public domain native SGML editors although a number of commercial SGML editors exist on a variety of platforms and most capable of supporting any SGML litprog scheme. For a long time I've been thinking about (sigh... not doing anything about) hooking one of the public domain SGML parsers into Emacs and using read-only zones to represent the and tags that mark-up document structures. With a fair deal of custom mode work an Emacs user would have a nice environment for editing SGML without having to learn a whole new editor. Maybe some kind soul has already done this. I just don't know what's out there right now. -- Andrew Dobrowolski (aed@arbortext.com) P.S., Sorry from the digression from the litprog stream. Disclaimer: the opinions expressed here are my own and do not in any way represent the opinions of my employer. ================================================================================ Archive-Date: Fri, 21 Jan 1994 05:49:05 CST Sender: LP-Mgr@SHSU.edu From: carroll@nori.cis.udel.edu (Mark C. Carroll) Reply-To: LitProg@SHSU.edu, carroll@NORI.CIS.UDEL.EDU Subject: Re: Importance of indexing? Date: 20 Jan 1994 22:06:18 GMT Message-ID: <2hmv8q$8l@louie.udel.edu> To: LitProg@SHSU.EDU In article shf@netcom.com (Stuart Ferguson) writes: >+-- carroll@nori.cis.udel.edu (Mark C. Carroll) writes: >| I'm currently working on an HTML based literate programming tool. > [...] >| I've got the tool working, but I don't do any indexing of variable >| definitions. I haven't implemented that, because I *never* look at the >| things when I read a literate program. (They wouldn't be too hard to >| add, but the addition of the index would involve some rather un-SGML >| like contortions, which I've been trying to avoid.) > >Just a thought -- but doesn't HTML support a form of hypertext? >If so, why not have the symbol references be linked back to their >definition site? Well, strictly speaking, HTML doesn't *support* a form a hypertext; it *is* a form of hypertext. The reason that I'm avoiding the idea of linking symbol references back to their definition sites is because for the applications I'll be using this for, it doesn't make any sense. Linking symbols to definitions only works if there is exactly one definition for each symbol - and that's not the case in programs that I write. I do most of my work in object-oriented languages, where a given symbol will have a list of definition sites. My reason for being biased against use indexing is related to this. If each symbol has multiple definitions, then a naively generated use index is going to lump together all uses of a given name together, even though they are references to different definitions. And there's no good way to automatically determine which definition is being referenced by a given use, without either given the weaver knowledge about the language, or requiring the programmer to provide the information. Since I don't want a language specific system, that leaves me with forcing the user to annotate uses. A little bit of toying around leads me to believe that annotating uses is cumbersome. But I'll probably give it a try, since so many people seem to think it's very important. How's this: by default, I assume that any uses of an identifier defined within the default index of a chunk will be references to the definition in that index. If the identifier is defined once within the index, then it can even insert a hyperlink to the definition. If it's outside of the current index, then we need some way to identify where we expect uses to come from, so the identifier gets marked in a u (for use) tag, which has an index field, as in the following: for (loopindex =0; loopindex<100; loopindex++) A question that naturally comes up here is: should all uses of an identifier be assumed to be interesting, or should the programmer mark interesting uses? That should take care of most things. Thinks with multiple definitions in an index can't get an automatically generated hyperlink unless I add some way of identifying the correct one. Frankly, I think that that's just overkill and not worth the effort. I'll always insert a link to the currently defined index at the end of the chunk, which you can follow, and check out the multiple links that occur in the index. -- || Mark Craig Carroll: ||"I live to see my fondest dreams realized, || CIS Grad, Univ of Delaware || Of living under the sights and sounds of || PGP key available by finger || the gifted, Who gave so much to me" || carroll@udel.edu || - _Feed_the_Fire_, Happy Rhodes ================================================================================ Archive-Date: Fri, 21 Jan 1994 05:53:20 CST Sender: LP-Mgr@SHSU.edu From: marcus@x4u2.desy.de (Marcus Speh) Reply-To: LitProg@SHSU.edu, marcus@X4U2.DESY.DE Subject: Re: HTML WEB Message-ID: Date: Fri, 21 Jan 1994 01:45:05 GMT To: LitProg@SHSU.EDU >>>>> "mckearney" == mckearney s writes: mckearney> I found a small program that converts TeX/LaTeX to RTF/HTML mckearney> (and some others) called tex2rtf. It seems to work quite mckearney> well I think (taking account of styles etc.) but I have not mckearney> really used it much. Because HTML is relatively simple, it mckearney> does not have to do a lot of work to produce a reasonable mckearney> output. This might be used to take nu/noweb output and mckearney> hypertext it? For more info on this tool on WWW, try http://info.desy.de/user/projects/C++.html from there, go to "Packages". At the lower end of the page, you find a link to http://info.desy.de/user/projects/C++/wxwindows/tex2rtf.html where I have installed the WWW doc for Julian Smart's tool. Marcus -- ----------------------------------------------------------------------------- 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 Email: , -- DECnet: 13313::SPEH ================================================================================ Archive-Date: Fri, 21 Jan 1994 06:08:59 CST Sender: LP-Mgr@SHSU.edu Date: Fri, 21 Jan 94 7:07:31 EST From: Lee Wittenberg Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET To: LitProg@shsu.edu, mauer@mcs.anl.gov Subject: Re: Indexing in Noweb Message-ID: Andrew Mauer writes: > All of this talk of indexing has made me wonder... I have tried to > make a use/def index in noweb, largely successfully. However, I am > curious why the mini-indices do not include references to other > definitions. (In other words, if you have an indentifier %def-ined in > two places and used nowhere else, the mini-indices in both places will > say "never used".) Is this a feature? I can see it could be useful in > some contexts, but sort of bothers me because it does not really > convey what is happening to the identifier in the rest of the program. Yes, this is a feature. You can use the hideunuseddefs option to remove the ``never used'' notice (leaving the definitions in the main identifier index, but you can't get the definitions cross-referenced to each other. I believe the rationale is that a definition is different than a use, and noweb has no way of telling that multiple references in a %def'ed chunk are not part of the same definition. For example, the C code struct xxx { /* ... */ } xxx; contains 2 instances of the identifer xxx, but they are both definitions. It might be possible that an ``autodef'' filter could put both @defn and @use markup in a chunk, and that noidx will behave accordingly, but I don't really know for sure. -- Lee leew@pilot.njin.net ================================================================================ Archive-Date: Fri, 21 Jan 1994 06:28:04 CST Sender: LP-Mgr@SHSU.edu From: evanss@kaa.ee.umist.ac.uk (Steven R Evans) Reply-To: LitProg@SHSU.edu, evanss@KAA.EE.UMIST.AC.UK Subject: Using WEB under DOS Message-ID: <1994Jan21.104113.12546@nessie.mcc.ac.uk> Keywords: WEB, DOS, Windows Date: Fri, 21 Jan 1994 10:41:13 GMT To: LitProg@SHSU.EDU I am working on a project developing Computer based learning software running under MS-windows, using Borland C++. I am thinking of using WEB, can anyone tell me: 1) what software I need 2) where I can get the software 3) How i learn to use it. P.S. The I know very little about WEB except it is suposed to produce well documented maintanable code. ************************************** * Dr Steven R Evans * * Email :evanss@kaa.ee.umist.ac.uk * ************************************** ================================================================================ Archive-Date: Fri, 21 Jan 1994 07:07:50 CST Sender: LP-Mgr@SHSU.edu Date: Fri, 21 Jan 94 8:07:31 EST From: Lee Wittenberg Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET To: LitProg@shsu.edu, evanss@kaa.ee.umist.ac.uk Subject: Re: Using WEB under DOS Message-ID: Steven Evans asks: > I am working on a project developing Computer based learning software running under MS-windows, using Borland C++. I am thinking of using WEB, can anyone tell me: > > 1) what software I need > 2) where I can get the software > 3) How i learn to use it. 1) CWEB, FWEB, or one of the language independents: noweb, nuweb, FunnelWEB, CLiP, WinWordWEB. More info on each is available in David Thompson's excellent LP FAQ. The following sections are quoted verbatim from 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 Sam Houston State University > (SHSU). Send a message to FILESERV@SHSU.EDU (FILESERV@SHSU.BITNET) and > include in your message > > SENDME LITPROG.FAQ > > The file server will forward a copy of the file to you via email. > The CTAN sites are: > > ftp host IP CTAN root Institution and Sponsor > ------------------------------------------------------------------------- > ftp.TeX.ac.UK 134.151.79.32 pub/archive Aston Univ./UK TeX U.G. > ftp.Uni-Stuttgart.DE 129.69.8.13 soft/tex Univ. Stuttgart/DANTE e.V > ftp.SHSU.edu 192.92.115.10 tex-archive Sam Houston State Univ. 2) see the FAQ 3) ditto Sorry to be so tight-lipped, but all the information you want is in the FAQ. Not much point in copying the whole thing. -- Lee leew@pilot.njin.net ================================================================================ Archive-Date: Fri, 21 Jan 1994 07:55:40 CST Sender: LP-Mgr@SHSU.edu Date: Fri, 21 Jan 94 14:55:07 +0100 From: Reino de Boer Reply-To: LitProg@SHSU.edu, sysrb@CS.FEW.EUR.NL Message-ID: <9401211355.AA28534@cs.few.eur.nl> To: LitProg@SHSU.edu, carroll@NORI.CIS.UDEL.EDU Subject: Re: Importance of indexing? > From LP-Mgr@SHSU.edu Fri Jan 21 13:18:08 1994 > From: carroll@nori.cis.udel.edu (Mark C. Carroll) > Subject: Re: Importance of indexing? > Message-Id: <2hmv8q$8l@louie.udel.edu> First of all, let me say that I cheer the use of HTML for literate programming. And, I like the idea of having more than one index. In nuweb I use nuweb's indexing for user-identifiers, and LaTeX's indexing for standard identifiers. For statistics: I'm using nuweb (and some cweb). > In article > shf@netcom.com (Stuart Ferguson) writes: > >Just a thought -- but doesn't HTML support a form of hypertext? > >If so, why not have the symbol references be linked back to their > >definition site? > > Linking symbols to > definitions only works if there is exactly one definition for each > symbol - and that's not the case in programs that I write. I do most > of my work in object-oriented languages, where a given symbol will > have a list of definition sites. Maybe the Next/Previous tags, that are being suggested for HTML+, can be used to create a (virtual) list of definitions to browse. Reino -- Reino R. A. de Boer CS Dept, Faculty of Economics, Erasmus University Rotterdam email: sysrb@cs.few.eur.nl There exists a way to compile TeX (Knuth 1985). ================================================================================ Archive-Date: Fri, 21 Jan 1994 08:30:42 CST Sender: LP-Mgr@SHSU.edu From: rob@comp.lancs.ac.uk (Robert Lougher) Reply-To: LitProg@SHSU.edu, rob@COMP.LANCS.AC.UK Subject: Hypertext in Software Development Message-ID: <1994Jan21.125640.26469@comp.lancs.ac.uk> Date: Fri, 21 Jan 1994 12:56:40 GMT To: LitProg@SHSU.EDU There has been quite a few articles posted recently about the use of HTML and SGML in literate programming. It seems as if there is a hell of a lot of interest in using hypertext etc. as a means of augmenting existing LP systems. For example, a number of people (sorry I can't remember who) have mentioned using hypertext links to link definitions and usages together. There has also been mentions of the importance of supporting maintenance, as this is the most costly part of the life-cycle. This is where I come in! I've been working on this area towards my PhD and have built a prototype tool to support what can be called a hypertext approach to documenting and browsing software. As many of the issues are related to what's been talked about, I thought people might be interested in it... First of all, the major interest of our work was documentation support for software maintenance, especially as a means of supporting collaboration between team members. Maintenance programmers spend much of their time understanding other people's code and it is for them documentation should be produced. However, as anybody who has ever tried to maintain code knows, a lot of code has documentation which is inadequate or non-existant. A major concern was therefore that the tool should support the process of redocumentation during maintenance. There's no reason, however, why the system can't be used during development. We use the term "rationale" to illustrate the fact that a wide variety of information should be able to be recorded, not just traditional stuff such as what this function is used for. For example, this might be comments from an inspection. A number of papers have been published describing the work: "Group Support for the Recording and Sharing of Maintenance Rationale", Robert Lougher and Tom Rodden, IEE/BCS Software Engineering Journal, November, 1993. "Supporting Long-term Collaboration in Software Maintenance", Robert Lougher and Tom Rodden, presented at the Conference on Organisational Computing Systems (COOCS'93), Nov. 1-5, Milpitas, CA, ACM. Here's the abstract from the first paper. "This paper presents a system which supports maintenance by allowing members of a maintenance team to easily construct and structure a shared pool of maintenance information. Through the provision of a range of unconstrained documentation facilities, documentation can be constructed incrementally by any member of the maintenance team. The general model adopted exploits hypertext technology to allow documentation to be integrated into the source code, by linking comments to the appropriate source component. Structuring facilities are provided which allow the source code and documentation to be seen at different levels of abstraction, in addition to a comment typing mechanism which allows different types of information to be explicitly represented." The system is essentially an interactive program editor in which hypertext links are displayed by highlighting. Different comment types are displayed using different styles of highlighting, i.e, foreground/background colour, bold etc. Documentation is created by annotation, i.e., the use of a variable might be explained by linking a "Variable Usage" comment to it. The editor in addition supports a wide range of facilites. These include cross-referencing (variables, functions etc.), folding, whereby sections of code can be grouped and folded away, display filters and graphical overviews of the network. Filtering allows complex queries to be formulated, i.e. show me all the "Bug Reports" created by Fred since last week. The overviews include views of the fold structure and graphs of the hypertext net. The system supports multiple files. Here's the bit relevant to the current discussion. The documentation is stored in the source code files via a markup language. Rather than use an existing standard, I developed my own. As has been mentioned in previous posts, the syntax of SGML is complex. I think one of the reasons literate programming hasn't been as successful as it could have is that the print-out may be pretty, the code is however, less readable than it was before. This would be even worse with SGML. My markup syntax is simple. It has been designed to alter the appearance of the source code as little as possible. All information is commented out according to the convention of the language being used. This means the source code is still compilable (i.e. no tangling) and it may still be edited in a normal editor. A previous poster mentioned the problem of linking definitions and uses together. I take the same approach and allow the user to indicate which should be linked. This was to keep the system language independent. The markup language's syntax is simple enough however, to allow the source code to be automatically marked up where suitable cross-referencing tools are available (i.e. cxref for C). The papers are also available as technical reports from the department. I'm currently writing my thesis so I'd welcome any comments. Robert Lougher. JANET : rob@uk.ac.lancs.comp | POST: Department of Computing, Internet: rob@comp.lancs.ac.uk | University of Lancaster, Tel. : +44 524 65201 Ext. 4117 | Lancaster, LA1 4YR Fax. : +44 524 381707 | ENGLAND ================================================================================ Archive-Date: Fri, 21 Jan 1994 09:30:56 CST Sender: LP-Mgr@SHSU.edu From: drmacro@vnet.IBM.COM Reply-To: LitProg@SHSU.edu, drmacro@VNET.IBM.COM Message-ID: <19940121.064612.137@almaden.ibm.com> Date: Fri, 21 Jan 94 09:22:57 EST Subject: Re: SGML and software development To: LitProg@SHSU.EDU In <2hma3k$lo6@gorgon.gatwick.sgp.slb.com> Steve Heaney writes: : An few thoughts that I'd appreciate some input on please. : : It occurs to me that SGML (the Standard Generalised Markup Language) : provides many possibilities for supporting a software development : environment.... : : Maybe someone has tried some of this already. I would be very interested : if anyone has DTD's or DTD fragments for program specification or design, : especially if these have been coupled with tools for generating or validating : the resultant source code. There are several products that are at least potentials for this, including Passage Systems' PassagePRO, MicroStar's Computer Aided Document Engineering (CADE) system, InfoDesign's WorkSmart, and Documentum's integration platform. Certainly the application of web-type approaches to code and documentation management is a natural for SGML. In fact we did this (sort of) to develop the IBMIDDoc DTD by making the source for the DTD primarily the source for the IBMIDDoc Reference and then creating a process that builds the working DTD from the documentation source (unfortunately, we didn't have the necessary SGML tools in place when we started so right now it's a DCF/Script process, not an SGML process). When I talk about designing SGML applications for technical information, I present the task as essentially one of relating information objects (the SGML elements) to objects in the data model for the system being documented (all real systems have a data models, whether it's been formalized or not, and since technical documentation is always about real systems (possibly systems of concepts), all technical documentation can be thought of as documenting objects in data models). The IBMIDDoc language, for example, uses and supports this approach explicitly. Once you get this far, that the information is always mapped to a data model, I go one more step and suggest that the information objects are in fact objects in the data model itself. In other words, the information about the system is part of the system itself. This should be obvious in the case of integrated online information like help or tutorials, but I think it works for all information, regardless of media. If you've gotten this far, I think it follows that in a CASE environment, there is no meaningful distinction between code and information and therefore no distinction (at a high level) between the tools used to create and manage code and information. And since SGML is, by its nature, generally the richest information source form (because of its generality), it makes sense that it would be the primary encoding for all data in the system, because everything else can be derived from it. --
Eliot Kimber Internet: drmacro@vnet.ibm.com Dept E14 (IZIP: 9141) IBMMAIL: USIB2DK9@IBMMAIL Network Programs Information Development Phone: 1-512-838-1734 IBM Corporation AltInternet: drmacro@aol.com Austin, TX 78758
================================================================================ Archive-Date: Fri, 21 Jan 1994 11:32:41 CST Sender: LP-Mgr@SHSU.edu From: lloyd@meaddata.com (Lloyd Harding) Reply-To: LitProg@SHSU.edu, lloyd@MEADDATA.COM Subject: Re: SGML and software development Date: 21 Jan 1994 16:41:52 GMT Message-ID: <2hp0kg$n8h@meaddata.meaddata.com> Keywords: SGML software literate process To: LitProg@SHSU.EDU In article <2hma3k$lo6@gorgon.gatwick.sgp.slb.com>, heaney@delft.sgp.slb.com (Steve Heaney) writes: |> An few thoughts that I'd appreciate some input on please. |> |> It occurs to me that SGML (the Standard Generalised Markup Language) |> provides many possibilities for supporting a software development |> environment. Because SGML provides the means of defining and verifying |> the content and structure of a "document" it offers, for example, |> the potential for coupling the documentation produced by software |> process (requirements, spec, design docs) with program source and beyond |> to maintenance manuals. |> |> This could take the form of a literate programming tool such as Web which |> combines source and documentation into one file. Alternatively it could form |> the basis of a more comprehensive CASE environment. Once you start thinking |> about it, many opportutities to exploit SGML occur. |> |> How about: |> |> - being better able to track requirements through specification, design |> and implementation. |> - supporting hypertext in your "source code". |> - generating or validating interfaces directly from your documentation. |> - formal validation of a program against assertions in the documentation. |> - defining a high level programming language which can be transformed |> into a number of target languages. |> |> Of course, none of these suggestions is immediately provided as an |> intrinsic feature of SGML - but SGML has the potential to provide an |> extensible, vendor neutral, language independent environment for software |> development with a few carefully thought out DTD's and the use of some |> of the software available on the net. |> |> Maybe someone has tried some of this already. I would be very interested |> if anyone has DTD's or DTD fragments for program specification or design, |> especially if these have been coupled with tools for generating or validating |> the resultant source code. |> I believe Exoterica did some work on this a number of years ago. If you find out any new directions and work, I would be interested. -- Lloyd Harding Mead Data Central lloyd@meaddata.com Data Architecture P.O. Box 933 uunet!meaddata!lloyd (513) 865-1076 Dayton, Ohio 45401 Fax: (513) 865-1755 ================================================================================ Archive-Date: Fri, 21 Jan 1994 17:52:32 CST Sender: LP-Mgr@SHSU.edu Date: Fri, 21 Jan 1994 18:42:43 -0500 (EST) From: j_mcarthur@BIX.com Reply-To: LitProg@SHSU.edu, j_mcarthur@BIX.COM Subject: RE: SGML and software development To: LitProg@SHSU.edu Message-ID: <9401211842.memo.96084@BIX.com> Content-Transfer-Encoding: 7BIT The more I deal with SGML the more I hate SGML. I like the concept of SGML. If the John Goldfarb had taken just a few classes in language design then SGML would be a wonderful idea. The problem I have is that SGML, in its current form, is such an awful hack. The syntax for dtd's is needlessly complex. SGML has the problem of creeping featurism. Consider the discussions in comp.text.sgml about ambiguous DTD's. Any language that allows you to create a "grammer", a.k.a DTD, that is ambiguous has serious problems. On thing I really hate about SGML is the way end-of-line is treated. Instead of being "white space" its meaning is context dependant. This means any tool that you use on an SGML file MUST understand the context. Unfortunately, SGML appears to be here to stay. Nothing else seems to match what SGML does. I prefer to work with a small subset of SGML; not the entire hideous beast. Jeffrey M\kern-.05em\raise.5ex\hbox{\b c}\kern-.05emArthur a.k.a. Jeffrey McArthur ================================================================================ Archive-Date: Fri, 21 Jan 1994 17:52:43 CST Sender: LP-Mgr@SHSU.edu Date: Fri, 21 Jan 1994 18:43:01 -0500 (EST) From: j_mcarthur@BIX.com Reply-To: LitProg@SHSU.edu, j_mcarthur@BIX.COM Subject: Re: SGML Literate Programming To: LitProg@SHSU.edu Message-ID: <9401211843.memo.96085@BIX.com> Content-Transfer-Encoding: 7BIT Literate programming is supposed to make programs easier to understand. Can anyone honestly say that the following is easy to understand? : : #include : : main() { : int i; : for (i=0;i<10;i++) : : } : Besides being ugly it is not even good ANSI C. There is no reason that < and > should be used for tagging. SGML allows you to use other characters. C/C++ programs generally only use the characters in the range [1-127]. This leaves 128 characters in that could be used for tag delimters. Pick any two and use them instead. Personally, I prefer literate programming tools that unstand and can pretty print the language. ---- Jeffrey M\kern-.05em\raise.5ex\hbox{\b c}\kern-.05emArthur a.k.a. Jeffrey McArthur ATLIS Publishing phone: (301) 210-6655 12001 Indian Creek Court fax: (301) 210-4999 Beltsville, MD 20705 email: j_mcarthur@bix.com ================================================================================ Archive-Date: Fri, 21 Jan 1994 20:37:11 CST Sender: LP-Mgr@SHSU.edu Date: Fri, 21 Jan 1994 21:19:56 -0500 (EST) From: j_mcarthur@BIX.com Reply-To: LitProg@SHSU.edu, j_mcarthur@BIX.COM Subject: Job Opening To: LitProg@SHSU.edu Message-ID: <9401212119.memo.96519@BIX.com> Content-Transfer-Encoding: 7BIT TITLE: Publication Programmer ATLIS Publishing is looking to fill a full time programming position. The ideal candidate has a background in TeX, Paradox (for DOS and Windows), Modula-2, and Pascal, Literate Programming, SGML, and Novell Networks. Primary job responsibility will be to design and implement a database application to publish directories. The application must run on a Novell Network using either DOS or Windows (or both). The application will generate the appropriate composition files to be processed via TeX. Development of the macros for TeX is also necessary. Duties will include the design of the user-interface, design of the database, creation of the database, importing existing data, doing integrity checks of the existing data, designing reports as well as designing both the composition file for TeX and the TeX macros. Familiarity with several programming languages is needed. If all you know is C and/or C++ we don't want you. Ideally code will be developed using literate programming techniques (i.e. WEB). Development tools include, but are not limited to: Borland Pascal, Logitech Modula-2, TopSpeed Modula-2, Paradox 4.0 and 4.5 for DOS, the Paradox Engine, Lex and Yacc (Pascal versions). Multi-language projects are common. All applications must run as multi-user applications on a Novell Network. Understanding of Novell API is desirable. Knowledge of SGML is highly desirable. Currently TeX is used to typeset SGML documents. Understanding how fonts are used by TeX is highly desirable. Must be fluent in English. ATLIS Publishing is located in Beltsville, Maryland. Just outside the DC Beltway. ATLIS provides flexible hours in a non-smoking environment. Interested candidates should send a resume and salary history (required) to: ATLIS Publishing ATTN: Melissa Colbert 12001 Indian Creek Court Beltsville, MD 20705 Or email the to j_mcarthur@bix.com. Or fax to 301-210-4999/4998/4997. NO PHONE CALLS. ================================================================================ Archive-Date: Sat, 22 Jan 1994 00:04:50 CST Sender: LP-Mgr@SHSU.edu From: tfee@vanbc.wimsey.com (Thomas Fee) Reply-To: LitProg@SHSU.edu, tfee@VANBC.WIMSEY.COM Subject: Re: SGML and software development Date: 21 Jan 1994 21:31:18 -0800 Message-ID: <2hqdn6$nr1@vanbc.wimsey.com> To: LitProg@SHSU.EDU In article <19940121.064612.137@almaden.ibm.com>, wrote: >And since SGML is, by its nature, >generally the richest information source form (because of its generality), >it makes sense that it would be the primary encoding for all data >in the system, because everything else can be derived from it. >-- >Eliot Kimber Internet: drmacro@vnet.ibm.com It is weak in several areas: 1) Freehand drawings 2) Animations with 3) Voice annotation We will be putting in a CASE strategy pretty soon. It's my objective to have those three things. (Video is nice but too much storage is required.) You can get it rather easily if you're not hung up on a rigid model such as SGML. The objective is to bring the cost of recording design ideas and decisions down to almost zero as far as the analysts/designers/programmers are concerned. -------- Thomas Fee Greater Vancouver Regional District, IT Architect/Planner 604.436.6923 Vancouver, British Columbia, Canada ================================================================================ Archive-Date: Sat, 22 Jan 1994 05:22:31 CST Sender: LP-Mgr@SHSU.edu From: rdmastro@jpmorgan.com (Richard DelMastro,gov) Subject: Re: Screen Saver help Date: 21 Jan 1994 14:37:35 GMT Message-ID: <2hopbf$nf1@archive.ny.jpmorgan.com> Reply-To: LitProg@SHSU.edu, rdmastro@jpmorgan.com To: LitProg@SHSU.EDU In article 2h4ndsINN1dr@uwm.edu, flea@csd4.csd.uwm.edu (Kimberly Anne Stinson) writes: > I have just finished writing a very rudimentary screen saver in QBasic 4.5. > It runs fine from an .exe file, but that is not the point of a screen saver. > I want to be able to have it run automatically after a period of, say, 5 > minutes.. just like any other screen saver. I could probably work it in > either basic or C (maybe some type of call command to pull the .exe file?), and any help by email is -greatly- appreciated. > > -- > Kimberly Anne Stinson University of Wisconsin - Milwaukee > Philosophy / Architecture You only -wish- you were crazy. Why is this posted to comp.programming.literate? --- Richard Del Mastro rdmastro@jpmorgan.com ================================================================================ Archive-Date: Sat, 22 Jan 1994 10:37:48 CST Sender: LP-Mgr@SHSU.edu From: jpq@casbah.acns.nwu.edu (John Quintana) Reply-To: LitProg@SHSU.edu, jpq@CASBAH.ACNS.NWU.EDU Subject: Literate Programming, Folding editors etc... Date: 22 Jan 1994 15:05:36 GMT Message-ID: <2hrfc0$g5q@news.acns.nwu.edu> To: LitProg@SHSU.EDU I have been using funnelweb under DOS as well as SunOS now for about 6 months. So far, I have had great success with it. Recently, I had to revisit my first project and found the literate programming approach to be extremely valuable. Currently, I'm working on a system for performing instrument control on PC's through a TCP/IP link using TCL that uses three separate languages: TCL, C (under DOS and UNIX), and DOS assembler. Basically, different TCP/IP ports are bound to individual TCL interpreters. Hardware control primitives are coded in C and assembler and then registered with the interpreters (i.e. the 'standard' tcl model). Juggling all three of these languages even within the literate programming environment started to become a hassle. That is, until I discovered folding editors which allows me to segment the different documentation, code segments etc... within the same document. It does not provide cross referencing via hypertext, but I tend to follow a similar conceptual structure for organizing all my programs, so I know where to find things. If you are currently using any literate programming system, you may wish to look at either the folding-mode under Emacs, or a shareware version of a folding editor under DOS available from SIMTEL. Both could stand to have a few more features that would support literate programming. I have not yet looked at using the emacs folding mode with its hyperbole hypertext system, but this might be a good blend. Has anyone else tried this approach? ================================================================================ Archive-Date: Sat, 22 Jan 1994 10:49:09 CST Sender: LP-Mgr@SHSU.edu From: ziegler@mpi-sb.mpg.de (Joachim Ziegler) Subject: Indexing Date: 22 Jan 1994 16:02:37 GMT Message-ID: <2hrimtINNmau@sbusol.rz.uni-sb.de> Reply-To: LitProg@SHSU.edu, ziegler@mpi-sb.mpg.de To: LitProg@SHSU.EDU I use CWEB for "webbing" C++ programs. I would like to ask other users if they miss the same feature as I do: At the end of each section, you get the references "See also Section blah blah ..." and "This code is used in Section blah blah ...". But what I really miss is that for each function call in the C++ portion of a section there should be a reference to where the code of this function is really defined, not declared, that means something like this: "For the definition of function foo() see Section X.". Looking at the index table at the end of the tex-output may make you search through a lot of sections until you find the code of a specific function. Any opinions? --- ******************************************************* * Joachim Ziegler Universitaet des Saarlandes * ******************************************************* * Though my wife still respects me I really misuse her* * I am having an affair with a random computer * * Don't you know, I'm the 2000 man * * And my kids they just don't understand me at all * * * * The Rolling Stones * ******************************************************* ================================================================================ Archive-Date: Sat, 22 Jan 1994 11:27:39 CST Sender: LP-Mgr@SHSU.edu Date: Sat, 22 Jan 94 12:27:07 EST From: aed@arbortext.com Reply-To: LitProg@SHSU.edu, aed@ARBORTEXT.COM Message-ID: <9401221727.AA12124@ironwood.arbortext.com> To: LitProg@SHSU.edu, j_mcarthur@BIX.COM Subject: Re: SGML Literate Programming Jeffery McArthur (j_mcarthur@BIX.com) writes: Literate programming is supposed to make programs easier to understand. Can anyone honestly say that the following is easy to understand? : : #include : : main() { : int i; : for (i=0;i<10;i++) : : } : Besides being ugly it is not even good ANSI C. There is no reason that < and > should be used for tagging. SGML allows you to use other characters. C/C++ programs generally only use the characters in the range [1-127]. This leaves 128 characters in that could be used for tag delimters. Pick any two and use them instead. Personally, I prefer literate programming tools that unstand and can pretty print the language. I agree that editing SGML with an ascii editor is not for the faint of heart. To ephasise your point one more time... the less than sign in the "for" loop of the above code fragment would have to be represented by the ascii character sequence "<". Fortunately with a customizable SGML editor and a good design for the literate programming application the code would not look anything like that. It would look more like an average page from "TeX: The Program". And the less than sign would look like a less than sign. -- Andrew Dobrowolski aed@arbortext.com ================================================================================ Archive-Date: Sat, 22 Jan 1994 12:08:13 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: Indexing Date: 22 Jan 1994 17:46:35 GMT Message-ID: <2hropr$g27@rs18.hrz.th-darmstadt.de> To: LitProg@SHSU.EDU In article <2hrimtINNmau@sbusol.rz.uni-sb.de>, ziegler@mpi-sb.mpg.de (Joachim Ziegler) writes: > > I use CWEB for "webbing" C++ programs. I would like to ask other > users if they miss the same feature as I do: At the end of each > section, you get the references "See also Section blah blah ..." and > "This code is used in Section blah blah ...". But what I really miss > is that for each function call in the C++ portion of a section there > should be a reference to wher> e the code of this function is really > defined, not declared, that means something like this: "For the > definition of function foo() see Section X.". Looking at the index > table at the end of the tex-output may make you search through a lot > of sections until you find the code of a specific function. Any > opinions? [I have reformatted your article. Please use the or key a few times for your next post. Thanks in advance.] CWEB does _not_ contain a C++ parser, so it does not know the difference between declaration and definition. Actually, due to the syntactic ambiguity of C++ this isn't easy to add, either. Even then, a pure syntactic recognition is not enough because one has to handle overloading and method redefinitions. (You remember, in every OO language you *cannot* be sure in general what function is used at a given place.) In addition, such a process would not crossref to other modules (that are usually implemented as other translation units in C++), you are stuck within one file. And, since this came up in the past in this context: Personally, I find the idea of putting more than one module in a *WEB source and extract them in different C++ files the most horrible thing I've ever heard of. That goes straight against everything we need and want in terms of software engineering. (Most of all: separation of concerns, information hiding, introduction of abstraction levels, encapsulation; in short, the whole concept of modularization blows away then.) I would rather abandon Literate Programming than abandon the things we learned about the construction of software systems the last twenty years. Happily, it isn't necessary... Cheers, Joachim -- =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= Joachim Schrod Email: schrod@iti.informatik.th-darmstadt.de Computer Science Department Technical University of Darmstadt, Germany ================================================================================ Archive-Date: Sat, 22 Jan 1994 13:34:31 CST Sender: LP-Mgr@SHSU.edu Date: Sat, 22 Jan 94 13:23:49 CST From: "C. M. Sperberg-McQueen" Reply-To: LitProg@SHSU.edu, U35395%UICVM.BITNET@SHSU.EDU Subject: RE: SGML and software development To: LitProg@SHSU.edu, j_mcarthur@BIX.COM On Fri, 21 Jan 1994 18:42:43 -0500 (EST) said: (among other things): >Consider the discussions in comp.text.sgml about ambiguous DTD's. >Any language that allows you to create a "grammer", a.k.a DTD, >that is ambiguous has serious problems. Hmm. Does this mean we can all forget about regular expressions, Backus Normal Form, Generalized Phrase Structure Grammar, and every other grammar formalism known to linguistics or computer science? They all allow the construction of ambiguous grammars, or did last time I read a book on parsing theory. >Unfortunately, SGML appears to be here to stay. Nothing else seems >to match what SGML does. I prefer to work with a small subset of >SGML; not the entire hideous beast. Fair enough; many of us who work some or all the time with tools which are not SGML-aware do use subsets. I understand your frustration with some aspects of SGML qua formal language; you even mention one of my pet hobby horses (record-end treatment). But the statement you make with which I agree most strongly is "Nothing else seems to match what SGML does." Nothing else even comes close. For serious work with textual information, SGML is head, shoulders, chest, belly, and thighs above all of its competitors. But perhaps a discussion of sgml and its strengths and weaknesses belongs on comp.text.sgml, not on comp.programming.literate -- sorry for the digression, literati! -C. M. Sperberg-McQueen ACH / ACL / ALLC Text Encoding Initiative University of Illinois at Chicago u35395@uicvm.uic.edu / u35395@uicvm ================================================================================ Archive-Date: Sat, 22 Jan 1994 16:09:22 CST Sender: LP-Mgr@SHSU.edu From: fiehler@eads.umsl.edu (Greg Fiehler) Reply-To: LitProg@SHSU.edu, fiehler@EADS.UMSL.EDU Message-ID: <9401222118.AA16912@eads> Subject: Novice Lit. Prog. needs help. Date: Sat, 22 Jan 94 15:18:22 CST To: LitProg@SHSU.EDU ================================================================================ Archive-Date: Sat, 22 Jan 1994 16:09:45 CST Sender: LP-Mgr@SHSU.edu From: fiehler@eads.umsl.edu (Greg Fiehler) Reply-To: LitProg@SHSU.edu, fiehler@EADS.UMSL.EDU Message-ID: <9401222125.AA16924@eads> Subject: Novice Lit. Prog. needs help Date: Sat, 22 Jan 94 15:25:19 CST To: LitProg@SHSU.EDU ================================================================================ Archive-Date: Sat, 22 Jan 1994 16:09:49 CST Sender: LP-Mgr@SHSU.edu From: fiehler@eads.umsl.edu (Greg Fiehler) Reply-To: LitProg@SHSU.edu, fiehler@EADS.UMSL.EDU Message-ID: <9401222117.AA16906@eads> Subject: Novice LitProg. needs help. Date: Sat, 22 Jan 94 15:17:19 CST To: LitProg@SHSU.EDU I am a Computer Science student and was just introduced to literate programming by a professor at UMSL. I have read much of Donald Knuth's Literate Programming book and have installed CWEB3.0 on a UNIX server. Looking at various example programs I decided to try Cameron Smith's K&R calculator example since it incorporates the ability to piece together separate source modules into one output document. However, I am having trouble getting it to work. The ctangle part works fine and I get a working executable. The separate .dvi's for each module are also correct, the problem is when it attempts to put it all together and create calc.dvi with one table of contents and one index. Also being a novice to TeX I am having trouble decifering the problem. Here is some of the error messages I am getting: . . . \modlistfile=\read0 (main.toc ! Missing control sequence inserted. \inaccessible { l.2 \ZZ { Introduction}{1}{1}{1} ?h Please don't say `\def cs{...}', say `\def\cs{...}'. I've inserted an inaccessible control sequence so that your definition will be completed without mixing me up too badly. You can recover graciously from this error, if you're careful; see exercise 27.2 in The TeXbook. I've looked at the TeXbook and I understand minimally the problem but I can't figure out how to fix it from Mr. Smith's web files. The output I get from calc.dvi if I just press enter at every ? error prompt that TeX gives me has the following problems: -The table of Contents looks like this Source Module 1: main Section Page Introduction111 The main program142 Index1104 Source Module 2: getop Section Page Introduction111 The function getop()172Index1103 etc. -The next page says : (section # symbol(/S))1.1 MAIN 1.1 1Introduction. and that is all the rest is blank. -The next page has the large type "Source Module 1: MAIN" and sections 1, 2, and 3. -the next page : (/S)1.(/S)41The main program MAINTHIS IS THE ... (where the ... is the entire first paragraph of module main 1.and it just runs off the page. I think the following error may be tied with this: [1] *1 [2] *4 Overfull \hbox (949.4097pt too wide) has occurred while \output is active []\tensy x\tenrm 1.\tensy x\tenrm 41The main program \eightrm MAIN THIS IS THE MAIN SEGMENT FOR THE CALCULATOR PROGRAM FROM CHAPTER 4 OF KERNIGHAN AND RITCHIE 'S \tenit THE C PROGRAMMING LANGUAGE\eightrm , WHICH I'M USING AS A TEST TO SEE HOW [] HANDLES FUNCTION PROTOTYPES, SEPARATELY COMPILED MODULES, AND THE LIKE \tenrm 1.3| -Also besides page numbering being generally screwed up the final index only lists the titles Sections in Source Module 1:MAIN Sections in Source Module 1:GETOP ...etc. but lists no index between them. If anyone can help me figure this out or point me to another example of how to combine modules in CWEB I would appreciate it. Also any hints, tips, or suggestions for a beginner in Literate Programming or Tex would also be appreciated. Thankyou Gregg Fiehler email: fiehler@eads.umsl.edu ================================================================================ Archive-Date: Sat, 22 Jan 1994 16:55:07 CST Sender: LP-Mgr@SHSU.edu From: fiehler@eads.umsl.edu (Greg Fiehler) Reply-To: LitProg@SHSU.edu, fiehler@EADS.UMSL.EDU Message-ID: <9401222207.AA17140@eads> Subject: Novice Lit. Prog needs help Date: Sat, 22 Jan 1994 16:07:38 -0600 (CST) To: LitProg@SHSU.EDU I am a Computer Science student and was just introduced to literate programming by a professor at UMSL. I have read much of Donald Knuth's Literate Programming book and have installed CWEB3.0 on a UNIX server. Looking at various example programs I decided to try Cameron Smith's K&R calculator example since it incorporates the ability to piece together separate source modules into one output document. However, I am having trouble getting it to work. The ctangle part works fine and I get a working executable. The separate .dvi's for each module are also correct, the problem is when it attempts to put it all together and create calc.dvi with one table of contents and one index. Also being a novice to TeX I am having trouble decifering the problem. Here is some of the error messages I am getting: . . . \modlistfile=\read0 (main.toc ! Missing control sequence inserted. \inaccessible { l.2 \ZZ { Introduction}{1}{1}{1} ?h Please don't say `\def cs{...}', say `\def\cs{...}'. I've inserted an inaccessible control sequence so that your definition will be completed without mixing me up too badly. You can recover graciously from this error, if you're careful; see exercise 27.2 in The TeXbook. I've looked at the TeXbook and I understand minimally the problem but I can't figure out how to fix it from Mr. Smith's web files. The output I get from calc.dvi if I just press enter at every ? error prompt that TeX gives me has the following problems: -The table of Contents looks like this Source Module 1: main Section Page Introduction111 The main program142 Index1104 Source Module 2: getop Section Page Introduction111 The function getop()172Index1103 etc. -The next page says : (section # symbol(/S))1.1 MAIN 1.1 1Introduction. and that is all the rest is blank. -The next page has the large type "Source Module 1: MAIN" and sections 1, 2, and 3. -the next page : (/S)1.(/S)41The main program MAINTHIS IS THE ... (where the ... is the entire first paragraph of module main 1.and it just runs off the page. I think the following error may be tied with this: [1] *1 [2] *4 Overfull \hbox (949.4097pt too wide) has occurred while \output is active []\tensy x\tenrm 1.\tensy x\tenrm 41The main program \eightrm MAIN THIS IS THE MAIN SEGMENT FOR THE CALCULATOR PROGRAM FROM CHAPTER 4 OF KERNIGHAN AND RITCHIE 'S \tenit THE C PROGRAMMING LANGUAGE\eightrm , WHICH I'M USING AS A TEST TO SEE HOW [] HANDLES FUNCTION PROTOTYPES, SEPARATELY COMPILED MODULES, AND THE LIKE \tenrm 1.3| -Also besides page numbering being generally screwed up the final index only lists the titles Sections in Source Module 1:MAIN Sections in Source Module 1:GETOP ...etc. but lists no index between them. If anyone can help me figure this out or point me to another example of how to combine modules in CWEB I would appreciate it. Also any hints, tips, or suggestions for a beginner in Literate Programming or Tex would also be appreciated. Thankyou Gregg Fiehler email: fiehler@eads.umsl.edu ================================================================================ Archive-Date: Sat, 22 Jan 1994 17:06:38 CST Sender: LP-Mgr@SHSU.edu From: fiehler@eads.umsl.edu (Greg Fiehler) Reply-To: LitProg@SHSU.edu, fiehler@EADS.UMSL.EDU Message-ID: <9401222225.AA17155@eads> Subject: Apology Date: Sat, 22 Jan 1994 16:25:06 -0600 (CST) To: LitProg@SHSU.EDU Sorry about the blank postings and multiple copies. I was having trouble with my mail system and did not think the messages were sent. Again any help or comments pertaining to my earlier posting will be greatly appreciated. Gregg Fiehler email:fiehler@eads.umsl.edu ================================================================================ Archive-Date: Sun, 23 Jan 1994 03:25:52 CST Sender: LP-Mgr@SHSU.edu From: fiehler@eads.umsl.edu (Greg Fiehler) Reply-To: LitProg@SHSU.edu, fiehler@EADS.UMSL.EDU Message-ID: <9401230703.AA17453@eads> Subject: More on K&R ex. problem Date: Sun, 23 Jan 1994 01:03:56 -0600 (CST) To: LitProg@SHSU.EDU Thanks to Mr. Fuller for the quick reply and interesting reading material. I will not have a chance to closely check every suggestion found in your reply until Monday but I wanted to clarify some missing information. I am using CWEBversion 3.1 by Knuth and Levi and I am using g++ for the compiler. Also I am using TeX C Version 3.14t3 (format = plain 92.6.9). From all checks I am using the latest version of Mr. Smiths Calc program also (I ftp'd it from niord.shsu.edu). Thank you again and I will read through your discussions with Mr. Smith and see if I can discover my probelm. Gregg Fiehler email:fiehler@eads.umsl.edu ================================================================================ Archive-Date: Sun, 23 Jan 1994 03:28:38 CST Sender: LP-Mgr@SHSU.edu From: dak@messua.informatik.rwth-aachen.de (David Kastrup) Reply-To: LitProg@SHSU.edu, dak@MESSUA.INFORMATIK.RWTH-AACHEN.DE Subject: Re: Novice LitProg. needs help. Date: 23 Jan 1994 08:58:49 GMT Message-ID: <2hte89$suu@urmel.informatik.rwth-aachen.de> MIME-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit To: LitProg@SHSU.EDU References: <9401222117.AA16906@eads> fiehler@eads.umsl.edu (Greg Fiehler) writes: >I get a working executable. The separate .dvi's for each module are >also correct, the problem is when it attempts to put it all together and >create calc.dvi with one table of contents and one index. Also being >a novice to TeX I am having trouble decifering the problem. > Here is some of the error messages I am getting: > . > . > . >\modlistfile=\read0 > (main.toc >! Missing control sequence inserted. > > \inaccessible > > { >l.2 \ZZ { > Introduction}{1}{1}{1} >?h >Please don't say `\def cs{...}', say `\def\cs{...}'. >I've inserted an inaccessible control sequence so that your >definition will be completed without mixing me up too badly. >You can recover graciously from this error, if you're >careful; see exercise 27.2 in The TeXbook. > > I've looked at the TeXbook and I understand minimally the >problem but I can't figure out how to fix it from Mr. Smith's web >files. Starred section titles are ended with a period. Yes, LaTeX users, (and usual plain features users) one could hardly expect you to know that. Except that it is in the docs. So you have to write things like $*Introduction. However, I think here the rule applies: whenever some behaviour is that strange that you will only get it right when looking into the docs, probably something is misdesigned. At least this is how I interpret the error messages. If this were not the cause, next guess would be a version mismatch of webmac.sty and weave, but I think this less probable. > The output I get from calc.dvi if I just press enter at >every ? error prompt that TeX gives me has the following problems: > > -The table of Contents looks like this >Source Module 1: main Section Page > Introduction111 The main program142 Index1104 >[1] *1 [2] *4 >Overfull \hbox (949.4097pt too wide) has occurred while \output is active >[]\tensy x\tenrm 1.\tensy x\tenrm 41The main program \eightrm MAIN THIS IS THE >MAIN SEGMENT FOR THE CALCULATOR PROGRAM FROM CHAPTER 4 OF KERNIGHAN AND RITCHIE >'S \tenit THE C PROGRAMMING LANGUAGE\eightrm , WHICH I'M USING AS A TEST TO SEE > HOW [] HANDLES FUNCTION PROTOTYPES, SEPARATELY COMPILED MODULES, AND THE LIKE >\tenrm 1.3| > If anyone can help me figure this out or point me to another >example of how to combine modules in CWEB I would appreciate it. > Also any hints, tips, or suggestions for a beginner in Literate >Programming or Tex would also be appreciated. W E L L, one thing is that CWEB is a pretty specialized WEB system imposing its own views of document structure, typesetting style, prettyprinting, source language... on its users. I would suggest looking into a few other LitProg tools as well. Problem with CWEB is that it is a one-way street, more or less. You have to decide before starting the project whether to do it literate or not, and keep to that decision (no special characters allowed in comments, spspecific document structure...). As opposed to that there are WEBs around which make it rather easy to convert to and from Literate. For example, noweb's tangle will preserve indentation of modules when combining them, so that the resulting file will be highly readable, and not the least bit reformatted. There is a special tangle version for non-literate receivers of programs, which does put all the text section into comments. As a result, distributing non-literate excerpts of LPs is easy. Crossswitching, due to easy syntax, and blending into either TeX/LaTeX is also a boon. I'd check out noweb (if you got a Unix tool box) or nuweb (needs a C compiler) for first comparison. Check out the LitProg FAQ for other tools. At least noweb (nuweb I have not tried yet) makes it very easy to postpone the decision "Literate or not" until ridiculouly late (and then you can change your mind, still). This is a boon. CWEB, on the other hand, requires a definite decision, and then a later change is pretty hard. Too much discipline for me. -- David Kastrup dak@pool.informatik.rwth-aachen.de Tel: +49-241-72419 Fax: +49-241-79502 Goethestr. 20, D-52064 Aachen ================================================================================ Archive-Date: Sun, 23 Jan 1994 06:49:19 CST Sender: LP-Mgr@SHSU.edu Date: Sat, 22 Jan 1994 19:33:05 -0500 (EST) From: j_mcarthur@BIX.com Reply-To: LitProg@SHSU.edu, j_mcarthur@BIX.COM Subject: RE: SGML Literate Programming To: litprog@SHSU.edu Message-ID: <9401221933.memo.98514@BIX.com> Content-Transfer-Encoding: 7BIT >I agree that editing SGML with an ascii editor is not for the faint of >heart. To ephasise your point one more time... the less than sign in >the "for" loop of the above code fragment would have to be represented >by the ascii character sequence "<". Part of my philosophical disagreement is with using < and > for something they were not intended. < and > have a defined meaning in most computer languages: C, C++, Algol, Pascal, Modula-2, Ada, and so on. Forcing the less-than to be represented by < is counter-intuitive. This is counter to the whole concept of literate programming. If you show the SGML file to someone who has never seen a literate program they will not be able to understand it at all. With one of the WEB decendants that is not quite as bad a problem. The WEB programs were designed with formatting computer programs in mind. SGML was designed for tagging text. In convensional text less than and greater than are quite infrequent. In computer programming they are very common. Let me illistrate my point. Consider the following example: 8chunk name="a sample chunk" file="sample.c" index="mainindex"9 #include 8stdio.h9 8d9main8/d9() { int 8d9i8/d9; for (i=0;i<10;i++) 8cr ref="another chunk"9 } 8/chunk9 This is the same example but using 8 instead of < and 9 instead of >. This code is unreadable. You could, in theory, set up your sgml parser to accept this. 8, and 9 occur relatively infrequently and when they do you could type &eight; and &nine;. Do you see how ludicrous this is? On another point, most WEB tools are publicly available. They are well documented and easy to use. It is not that difficult to write you own. This is not true of SGML. SGML was designed by a lawyer. And it shows! The more I deal with SGML the more I hate it. It is a good idea gone very, very bad. I think SGML has the same problems as Algol-68. The full standard has everything but the kitchen sink included. Here is the final telling point. Write out a BNF grammer of the DTD you are using. (Unless you have defined an ambigous grammer this should be possible.) Now obtain a BNF grammer of your favorite programming language. Compare the size and complexity. In most cases the DTD will have a more complex grammer. That says alot about the complexity of SGML. (Of course you could do extreme examples like comparing Oberon to something like CALS.) ---- Jeffrey M\kern-.05em\raise.5ex\hbox{\b c}\kern-.05emArthur a.k.a. Jeffrey McArthur ATLIS Publishing phone: (301) 210-6655 12001 Indian Creek Court fax: (301) 210-4999 Beltsville, MD 20705 email: j_mcarthur@bix.com ================================================================================ Archive-Date: Sun, 23 Jan 1994 11:04:32 CST Sender: LP-Mgr@SHSU.edu From: chi@netcom.com (Curt Hagenlocher) Reply-To: LitProg@SHSU.edu, chi@NETCOM.COM Subject: Re: SGML Literate Programming Message-ID: Date: Sun, 23 Jan 1994 16:33:39 GMT To: LitProg@SHSU.EDU j_mcarthur@BIX.com writes: >Here is the final telling point. Write out a BNF grammer of the DTD >you are using. (Unless you have defined an ambigous grammer this should >be possible.) Now obtain a BNF grammer of your favorite programming >language. Compare the size and complexity. In most cases the DTD will >have a more complex grammer. That says alot about the complexity of >SGML. (Of course you could do extreme examples like comparing Oberon >to something like CALS.) Heh heh heh. Have you ever seen a COMPLETE grammar for C++? (Of course, MOST people just use a subset of C++ as well.) -- Curt Hagenlocher chi@netcom.com ================================================================================ Archive-Date: Sun, 23 Jan 1994 12:46:31 CST Sender: LP-Mgr@SHSU.edu From: carroll@bofur.cis.udel.edu (Mark C. Carroll) Reply-To: LitProg@SHSU.edu, carroll@BOFUR.CIS.UDEL.EDU Subject: Re: SGML Literate Programming Date: 23 Jan 1994 18:11:32 GMT Message-ID: <2huekk$9ia@louie.udel.edu> To: LitProg@SHSU.EDU In article <19520599@mvb.saic.com> j_mcarthur@BIX.com writes: >Literate programming is supposed to make programs easier to understand. >Can anyone honestly say that the following is easy to understand? > >: >: #include >: >: main() { >: int i; >: for (i=0;i<10;i++) >: >: } >: I rather disagree here... One of the biggest problems that I've found with literate programs is that the source code, in non-formatted form is an incredible mess for a human reader. The reason that I decided to implement the tool is precisely because I don't like reading literate code online. When I view in in pre-formatted form, there's so much extra noise that it's difficult to read. After formatting, I can only view it through a dvi viewer. What this ends up meaning, in my experience, is that you've got a computer system sitting in front of you, and you're completely unable to take advantage of the abilities of that computer to help you understand the code that you're reading. You can print the program on paper, or you can view it on virtual paper. I wanted to be able to experiment with a tool that would allow me to see my program in a useful form online, and to take some advantage from the fact that I was using a computer to view it. Given that goal, and given that I'm not at all sure that this is really going to be advantageous, I don't want to end up wasting too much time. So I'm working with what I have available. Realistically, what I have available to work with, without implementing a complete new hypertext system is either texinfo, or HTML. Given that choice, I did some experimenting, and decided that HTML is preferable. So I'm working within HTML syntax. Which is, admittedly rather ugly. But is it *really* all that much more ugly than a program marked up with TeX? Most of what makes the program above ugly is going to have to be present in *some* form. For my purposes, I cannot write a language specific tool (because I need to be able to work with perl, icon, C, C++, Eiffel, and perhaps Sather). So I need to provide *some* way of allowing the programmer to provide markup him/herself within the program to generate use/def links. Is the following *really* so much less ugly? <>= #include [[main]]() { int i; for (i=0;i<10;i++) <> } @ Personally, I don't really think so. And especially, since using abbreviations (and a minor syntactic change that I've done), it could be written: #include i; for (i=0;i<10;i++) >Besides being ugly it is not even good ANSI C. Sorry. I was just trying to throw together a quick example. It wasn't intended to be a paragon of fine programming! ... There is no reason >that < and > should be used for tagging. SGML allows you to use >other characters. C/C++ programs generally only use the characters >in the range [1-127]. This leaves 128 characters in that could be >used for tag delimters. Pick any two and use them instead. Well, there is a reason: a lot of the HTML parsers that exist are rather sensitive about syntax. In order to be fairly certain that they aren't going to choke on my, I'm trying to avoid *anything* that doesn't commonly occur in HTML documents. I've yet to see any HTML using anything as markup other than <>, so I'm sticking with the standard. >Personally, I prefer literate programming tools that unstand and can >pretty print the language. I've already explained why I'm avoiding language specific features. But there's really no reason why the code from chunks in this HTML syntax can't be piped through a formatter to do prettyprinting and definition marking automatically. -- [ Mark Craig Carroll ] You say you know no tricks, have no talents - [ U of Delaware, CIS Dept ] Isn't everyone supposed to have their own? [ PGP key available, ] Yes, but few are obvious. Few draw notice to those [ finger carroll@udel.edu ] who posess them, like flags waving themselves. ================================================================================ Archive-Date: Sun, 23 Jan 1994 13:32:08 CST Sender: LP-Mgr@SHSU.edu Date: Sun, 23 Jan 1994 12:31:38 CST X-MX-Warning: Warning -- Invalid "From" header. From: C. M. Sperberg-McQueen Reply-To: LitProg@SHSU.edu, U35395@UICVM.UIC.EDU Message-ID: <94023.123139U35395@uicvm.uic.edu> Subject: RE: SGML Literate Programming To: LitProg@SHSU.EDU If it had just been one posting, I would have ignored it, but two postings claiming that in an SGML-based literate programming system the line for (i=0;i<10;i++) would have to be represented for (i=0;i<10;i++) are too many for me. Even in the reference concrete syntax of SGML, the less-than sign in this line will not be mis-recognized as a start-tag delimiter, because it is not followed by a letter. If a variable name is substituted, the line can still be rewritten without resorting to an entity reference: for (i = startpoint; i < endpoint; i++) will cause no problems for any conforming parser. Some people will say white space, properly used, actually makes it more legible. If you don't like SGML for literate programming, don't use it. But before you pontificate on its syntax in public, perhaps you could be persuaded to learn a bit more about that syntax. The lawyer is several steps ahead of you. C. M. Sperberg-McQueen, University of Illinois at Chicago ================================================================================ Archive-Date: Sun, 23 Jan 1994 14:42:55 CST Sender: LP-Mgr@SHSU.edu Date: Sun, 23 Jan 1994 15:47:21 -0500 From: scott-ralph@MATH.YALE.EDU (Ralph Scott) Reply-To: LitProg@SHSU.edu, scott-ralph@MATH.YALE.EDU Message-ID: <199401232047.AA04683@NOETHER.MATH.YALE.EDU> To: LitProg@SHSU.edu Subject: signoff signoff ================================================================================ Archive-Date: Sun, 23 Jan 1994 19:08:26 CST Sender: LP-Mgr@SHSU.edu Message-ID: <199401240052.TAA04583@flaubert.bellcore.com> To: LitProg@SHSU.edu, evanss@kaa.ee.umist.ac.uk Subject: Re: Using WEB under DOS Date: Sun, 23 Jan 1994 19:52:25 -0500 From: Norman Ramsey Reply-To: LitProg@SHSU.edu, norman@BELLCORE.COM > P.S. The I know very little about WEB except it is suposed to produce well do > cumented maintanable code. Don't believe everything you hear. WEB is a very sharp sword, and novices can do things with it that make it hard for you to sleep at night. Take a look at Don Knuth's Stanford GraphBase and Literate Programming titles to get some idea of how to use WEB intelligently. Norman Ramsey ================================================================================ Archive-Date: Sun, 23 Jan 1994 19:08:42 CST Sender: LP-Mgr@SHSU.edu Message-ID: <199401240048.TAA04538@flaubert.bellcore.com> To: LitProg@SHSU.edu, mauer@mcs.anl.gov Subject: Re: Indexing in Noweb Date: Sun, 23 Jan 1994 19:48:49 -0500 From: Norman Ramsey Reply-To: LitProg@SHSU.edu, norman@BELLCORE.COM > All of this talk of indexing has made me wonder... I have tried to > make a use/def index in noweb, largely successfully. However, I am > curious why the mini-indices do not include references to other > definitions. (In other words, if you have an indentifier %def-ined in > two places and used nowhere else, the mini-indices in both places will > say "never used".) In noweb, a definition is not a use. Moreover, when it comes to formattin gthe mini-indices, uses in the same chunk as a definition are ignored (since they would convey no additional information). > Is this a feature? Beats me. Is it defensible? Yes. Is right? Dunno. > I can see it could be useful in > some contexts, but sort of bothers me because it does not really > convey what is happening to the identifier in the rest of the program. I don't have a listing handy to check, but I think the numbers of all defining chunks are listed where the identifier is listed, so you can find both definitions. Norman ================================================================================ Archive-Date: Mon, 24 Jan 1994 02:21:32 CST Sender: LP-Mgr@SHSU.edu From: coates@dingo.cc.uq.oz.au (Tony Coates) Subject: SGML and Literate Programming Date: 24 Jan 1994 07:25:53 GMT Message-ID: <2hvt61$3g6@dingo.cc.uq.oz.au> Reply-To: LitProg@SHSU.edu, coates@physics.uq.oz.au Keywords: literate programming sgml html To: LitProg@SHSU.EDU There have been a number of posts recently discussing the use of SGML/HTML mark-up techniques in constructing Literate Programming Tools. However, it seems to me that some recent posts for and against are arguing at cross-purposes. Particularly, I refer to the argument that ASCII SGML/HTML sources are difficult to read, at least compared to existing WEB sources. I won't deny that this point may be true; I would question though whether it is relevant. Virtually all the current WEB tools are batch oriented, taking ASCII sources and producing TeX output, which can later be viewed. Batch-mode operation is common with new types of programs, avoiding the complications of real-time interface handling, but personally I look forward to the day when the LitProg tools will be interactive, actively formatting the code as it is input, much like a modern word processor. Much as I like working with LaTeX for my sources, I don't see a lot being done by way of creating any kind or "real-time" TeX, which would work in other than batch mode. On the other hand, at least with the HTML extensions to SGML, hypertext offers interactive browsing of code, and in principle the marked-up code should be able to be formatted on the fly as required, I believe. So it seems to me that on that basis, SGML/HTML markups may offer useful advantages in generating a way of coding the literate programs so as to be able to exploit the featrues of HTML/SGML. Still, it is clear that if users were to be editing ASCII SGML sources, the experience might be off-putting. However, since SGML sources are meant to be for the machine, and in principle SGML editors which shield the user from such source code are suppose to be possible or even available, is the better question not that of how well the required mark-ups for literate programming could be added using a proper SGML editor, and what this would look like and feel like for the end-user? I have no experience with such editors, but would be interested to hear from someone who does. I sometimes imagine opening up a WYSIWYG editor, filled with documentation and code, and then highlighting a paragraph of code, selecting "Code" from the menu, and then defining the name of this code block, with the editor providing the appropriate formatting. If SGML editors could offer this, I for one would consider that building LitProg systems using SGML mark-ups as the base could be a worthwhile step forward. Anyway, this is long, but I did feel that too much was made of what SGML sources would look like, when this did not seem to me to be the question. Cheers, Tony. _____________________________________________________________________________ A.B.Coates, Dept. of Physics, The University of Queensland QLD 4072 Australia. Email: coates@physics.uq.oz.au Phone: (07/+617) 365-3424 Fax: (07/+617) 365-1242 Disclaimer: The University is ignorant of my opinions, let alone guilty ... _____________________________________________________________________________ ================================================================================ Archive-Date: Mon, 24 Jan 1994 06:54:29 CST Sender: LP-Mgr@SHSU.edu From: nikos@cbl.leeds.ac.uk (N F Drakos) Reply-To: LitProg@SHSU.edu, nikos@CBL.LEEDS.AC.UK Subject: Re: HTML WEB Date: Mon, 24 Jan 1994 11:51:38 GMT Message-ID: <1994Jan24.115138.29131@leeds.ac.uk> To: LitProg@SHSU.EDU Marcus Speh (marcus@x4u2.desy.de) wrote: : >>>>> "mckearney" == mckearney s writes: : mckearney> I found a small program that converts TeX/LaTeX to RTF/HTML : mckearney> (and some others) called tex2rtf. It seems to work quite : mckearney> well I think (taking account of styles etc.) but I have not : mckearney> really used it much. Because HTML is relatively simple, it : mckearney> does not have to do a lot of work to produce a reasonable : mckearney> output. This might be used to take nu/noweb output and : mckearney> hypertext it? : For more info on this tool on WWW, try : http://info.desy.de/user/projects/C++.html : from there, go to "Packages". At the lower end of the page, : you find a link to : http://info.desy.de/user/projects/C++/wxwindows/tex2rtf.html : where I have installed the WWW doc for Julian Smart's tool. Another conversion tool is latex2html. The latest version (0.5) will be uploaded to ftp.tex.ac.uk *soon*. Alternatively you can get it *now* via WWW and http from the "Getting LaTeX2HTML" section of the online manual at: http://cbl.leeds.ac.uk/nikos/tex2html/doc/latex2html/latex2html.html The online manual is an example of the capabilities of latex2html. Nikos. -- Nikos Drakos Computer Based Learning Unit nikos@cbl.leeds.ac.uk University of Leeds http://cbl.leeds.ac.uk/nikos/personal.html ================================================================================ Archive-Date: Mon, 24 Jan 1994 09:30:40 CST Sender: LP-Mgr@SHSU.edu From: schrod@iti.informatik.th-darmstadt.de (Joachim Schrod) Reply-To: LitProg@SHSU.edu, schrod@ITI.INFORMATIK.TH-DARMSTADT.DE Subject: Re: Using WEB under DOS Date: 24 Jan 1994 15:05:38 GMT Message-ID: <2i0o42$mdl@rs18.hrz.th-darmstadt.de> To: LitProg@SHSU.EDU In article <19567965@MVB.SAIC.COM>, Norman Ramsey writes: > > WEB is a very sharp sword, and > novices can do things with it that make it hard for you to sleep at > night. Thanks for this entry in my citation file, although you might not like to stand besides Dijkstra. :-) :-) -- Joachim On the one hand I knew that programs could have a compelling and deep logical beauty, on the other hand I was forced to admit that most programs are presented in a way fit for mechanical execution, but even if of any beauty at all, totally unfit for human appreciation. [Edsger Dijkstra] ================================================================================ Archive-Date: Mon, 24 Jan 1994 10:44:10 CST Sender: LP-Mgr@SHSU.edu From: yjc@po.cwru.edu (Jerome Chan) Reply-To: LitProg@SHSU.edu, yjc@PO.CWRU.EDU Subject: CWeb Mac Users? Date: Mon, 24 Jan 1994 11:07:48 -0500 Message-ID: To: LitProg@SHSU.EDU Has anyone tried using CWeb with Think C 6.0? What difficulties have you encountered (if any)? I'm about to start a programming class and I would like to use CWeb/Think C if it's possible. Thanks for any replies! -- The Evil Tofu (Only Human) ================================================================================ Archive-Date: Mon, 24 Jan 1994 11:15:21 CST Sender: LP-Mgr@SHSU.edu Date: Mon, 24 Jan 94 13:21:00 MET From: Zdenek Wagner Reply-To: LitProg@SHSU.edu, WAGNER%CSEARN.BITNET@SHSU.EDU Subject: Re: Indexing To: Literate Progaramming list , ziegler@mpi-sb.mpg.de On 22 Jan 1994 16:02:37 GMT said: >I use CWEB for "webbing" C++ programs. I would like to ask other users if they >m >iss the same feature as I do: >At the end of each section, you get the references "See also Section blah blah >. >.." and "This code is used in Section blah blah ...". But what I really miss is > >that for each function call in the C++ portion of a section there should be a >re >ference to where the code of this function is really defined, not declared, >that > means something like this: >"For the definition of function foo() see Section X.". Looking at the index >tabl >e at the end of the tex-output may make you search through a lot of sections >unt >il you find the code of a specific function. Any opinions? > >--- > >******************************************************* >* Joachim Ziegler Universitaet des Saarlandes * >******************************************************* >* Though my wife still respects me I really misuse her* >* I am having an affair with a random computer * >* Don't you know, I'm the 2000 man * >* And my kids they just don't understand me at all * >* * >* The Rolling Stones * >******************************************************* > I do not see such problem. Remember that CWEB (as any WEB) enables you to place any chunk anywhere which seems logical and convenient for you and ctangle rearranges them so that the compiler understands the program. If you have problems finding something in *your* programs, it only reveals that you still think as your compiler. Try to rearrange your web file in the way you best understand. This is one of the big advantages of LP. ,~~~/ /` / /| /~~~ / / |_/ /__/ ' | / / /~~/ /~~/ /~~/ /~~/ /\ | /| / /~~/ /~~/ /~~/ /~~/ /~~~ / , / / /~~~ / / /~~~ / \ |/ |/ / /_/ / / / /~~~ / ~~~~ ~~~ ~~~ ' ' ~~~ ' ` ' ' ~~~ ~~/ ' ' ~~~ ' Zdenek Wagner______/ Some gateway between me and you may garble backslash. It will appear on your screen as ã due to problems with EBCDIC <--> ASCII conversion. It has already been corrected on SOME gateways. The domain `.cs' does no longer exist and was replaced by `.cz'. Valid addresses are: ^^ ================================================================================ Archive-Date: Mon, 24 Jan 1994 11:32:16 CST Sender: LP-Mgr@SHSU.edu Date: Mon, 24 Jan 94 12:29:17 EST From: Lee Wittenberg Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET To: LitProg@shsu.edu, rob@comp.lancs.ac.uk Subject: Re: Hypertext in Software Development Message-ID: Robert Lougher says (among other things I happen to agree with): > ... I think one of the reasons > literate programming hasn't been as successful as it could have is that > the print-out may be pretty, the code is however, less readable than it was > before. This would be even worse with SGML. My markup syntax is simple. > It has been designed to alter the appearance of the source code as little > as possible. All information is commented out according to the convention > of the language being used. This means the source code is still compilable > (i.e. no tangling) and it may still be edited in a normal editor. I disagree with this. I literate code more readable. Remember that what is traditionally source is designed to be filtered before being read. Through tangle, if the reader is a compiler; through weave, if the reader is human. In addition, I find that even without explanations, code written as code chunks is much easier to digest, particularly when it's someone else's code. I'm experimenting with this with my CS1 students (more on this in a later message), and they seem to find untangled webs easier to understand than the complete ("tangled") program, primarily because the chunks remain small and complete in themselves. -- Lee leew@pilot.njin.net ================================================================================ Archive-Date: Mon, 24 Jan 1994 12:27:52 CST Sender: LP-Mgr@SHSU.edu From: glv@metronet.com (Glenn Vanderburg) Reply-To: LitProg@SHSU.edu, glv@METRONET.COM Subject: Re: SGML Literate Programming Date: Mon, 24 Jan 1994 16:44:45 GMT Message-ID: To: LitProg@SHSU.EDU In article <19520599@mvb.saic.com>, wrote: >Literate programming is supposed to make programs easier to understand. >Can anyone honestly say that the following is easy to understand? [Silly example of C code marked up with SGML tags deleted] >Personally, I prefer literate programming tools that unstand and can >pretty print the language. So do I. Which is why I am very interested in a literate programming tool based on SGML. When I read your posting, I spotted a couple of assumptions you made which are bogus. Here are my contrary views; 1. Most users of decent SGML applications will not need to read the SGML source. I know SGML, and I actually *like* the choice of `<' and `>' as tag delimiters. But I have no desire to work with the SGML source in a text editor, and I consider any SGML browser/editor which requires that to be crippled. I want a literate programming tool which will permit me to work online with something that resembles the formatted, printed result of the WEAVE process. I think that SGML makes that an easier task. 2. Everything in an SGML document does not have to be marked up with SGML tags for an SGML processor to understand its structure. Learn about SGML's notion of `notations'. C is a perfect example of a data notation which is not defined in terms of SGML. A notation parser which knows C will not need SGML tags to recognized declarations. That information is already present in the C notation, and the C parser can cooperate with the SGML parser, informing it of the structure. If I were designing an SGML literate programming application, your example would be marked up like this: #include main() { int i; for (i=0;i<10;i++) } That's much more reasonable, and as I've already said, users of the application should see this presented in an even nicer way. I can't criticize you too much for making those false assumptions, because SGML applications that really work this way are rare and expensive. And you do make some good points. SGML is feature-laden, and some of the features (like data tags, short references, and some of the other minimization features) are useful primarily to people who will be working directly with the SGML encoding. But I think that soon, applications will be available which hide that from users. Regards, Glenn Vanderburg ================================================================================ Archive-Date: Mon, 24 Jan 1994 14:24:44 CST Sender: LP-Mgr@SHSU.edu Date: Mon, 24 Jan 94 14:24:14 CST From: thompson@sun1.coe.ttu.edu (Dave Thompson (3/1/93)) Reply-To: LitProg@SHSU.edu, thompson@SUN1.COE.TTU.EDU Message-ID: <9401242024.AA20378@sun1.coe.ttu.edu> To: LitProg@SHSU.edu Subject: Re: Hypertext in Software Development CC: thompson@sun1.coe.ttu.edu > ... In addition, I find that even without > explanations, code written as code chunks is much easier to digest, > particularly when it's someone else's code. I'm experimenting with > this with my CS1 students (more on this in a later message), and they > seem to find untangled webs easier to understand than the complete > ("tangled") program, primarily because the chunks remain small and > complete in themselves. Has anyone documented the difference in readability? -=d ======================================================================= David B. Thompson internet: thompson@sun1.coe.ttu.edu Civil Engineering Dept. internet: dthompson@coe2.coe.ttu.edu Texas Tech University internet: wqdbt@ttacs1.ttu.edu P.O. Box 41023 Lubbock, Texas 79409-1023 "Get a haircut and get a *real* job." ======================================================================= ================================================================================ Archive-Date: Mon, 24 Jan 1994 16:44:24 CST Sender: LP-Mgr@SHSU.edu Message-ID: <199401242233.RAA06683@flaubert.bellcore.com> To: LitProg@SHSU.edu, carroll@nori.cis.udel.edu CC: bart@cs.tamu.edu (Bart Childs) Subject: Re: Request for comments: literate hypertext indices Date: Mon, 24 Jan 1994 17:33:50 -0500 From: Norman Ramsey Reply-To: LitProg@SHSU.edu, norman@BELLCORE.COM > > #include > > main() { > int i; > for (i=0;i<10;i++) > > } > This kind of markup is useful only if it can be hidden from users by a suitable editor. I applaud any attempt to build such an editor, provided details like this can be hidden from those who don't care to tinker with the implementation. One suggestion: if you can map existing web files (noweb, nuweb, cweb, fweb, or funnelweb) into your notation, people will be more willing to try out your editor. Only noweb is designed to make this exercise easy, but it shouldn't be too bad with nuweb because the feature set there is pretty small. For extra bonus points, make it possible to map in the opposite direction also. It might be worth studying Marcus Brown's work to find out what's already been done in the realm of interactive support for literate programming. Norman ================================================================================ Archive-Date: Mon, 24 Jan 1994 19:41:23 CST Sender: LP-Mgr@SHSU.edu From: ers@xgml.com (Eric R. Skinner) Reply-To: LitProg@SHSU.edu, ers@XGML.COM Subject: Re: SGML and software development Message-ID: <1994Jan24.160901.11276@xgml.com> Keywords: SGML software literate process Date: Mon, 24 Jan 1994 16:09:01 GMT To: LitProg@SHSU.EDU In article <2hma3k$lo6@gorgon.gatwick.sgp.slb.com> heaney@delft.sgp.slb.com writes: >It occurs to me that SGML (the Standard Generalised Markup Language) >provides many possibilities for supporting a software development >environment. Because SGML provides the means of defining and verifying >the content and structure of a "document" it offers, for example, >the potential for coupling the documentation produced by software >process (requirements, spec, design docs) with program source and beyond >to maintenance manuals. > [...] >Maybe someone has tried some of this already. I would be very interested >if anyone has DTD's or DTD fragments for program specification or design, >especially if these have been coupled with tools for generating or validating >the resultant source code. Exoterica's OmniMark product contains our commercial SGML parser, the SGML Kernel. The Kernel is built using an approach similar to what you described in your posting. The Kernel is in fact coded in an SGML markup language, combining engineering documentation with source code in a language close to C. The coding language is extended using SGML-defined constructs to provide a notation specifically useful for writing SGML parsers. It's a Web-like approach, but more powerful as code and documentation are more closely integrated. Our OmniMark product is then used to read this SGML document and generate C code, or to generate various types of documentation. OmniMark can also perform a variety of consistency checks. We also have an internal highly-detailed marked up version of ISO8879 which we use for many purposes, including the generation of our online hypertext version of the standard, part of the "Compleat SGML". The markup in this document is rich enough that it allows OmniMark to generate some C code for the Kernel directly from the markup of ISO8879's productions. The advantages we found in this type of development were many, including greater ease of coding, documentation, and faster development of high-quality code. Regards, -- Eric R. Skinner ers@exoterica.com Exoterica Corporation Tel +1 613 722 1700 Ottawa, Canada Fax +1 613 722 5706 Product information: info@exoterica.com ================================================================================ Archive-Date: Mon, 24 Jan 1994 20:00:29 CST Sender: LP-Mgr@SHSU.edu Message-ID: Date: Mon, 24 Jan 94 16:12 PST To: LitProg@SHSU.edu Subject: SGML and Literate Programming References: <2hvt61$3g6@dingo.cc.uq.oz.au> From: Kayvan Sylvan Reply-To: LitProg@SHSU.edu, kayvan@SATYR.SYLVAN.COM >>>>> "Tony" == Tony Coates writes: Tony> There have been a number of posts recently discussing the use of Tony> SGML/HTML mark-up techniques in constructing Literate Tony> Programming Tools. However, it seems to me that some recent Tony> posts for and against are arguing at cross-purposes. Tony> Particularly, I refer to the argument that ASCII SGML/HTML Tony> sources are difficult to read, at least compared to existing WEB Tony> sources. I won't deny that this point may be true; I would Tony> question though whether it is relevant. [...] Exactly. It seems to me analogous to arguing that one should not write computer programs because the underlying sequences of ones and zeros are hard to understand. The SGML/HTML markup is for use by tools that would hide the ugly details from the users. I program in WEB because I want some protection from the ugly details of the programming language ;-). I would welcome a chance to program in an interactive HTML editor that would protect me from the ugly details of WEB. 1/2 :-) ---Kayvan | Kayvan Sylvan, Sylvan Associates, kayvan@satyr.Sylvan.COM, (408) 978-1407 | | Consulting, Training, Development, SysAdmin, {BSD,SVr3,SVr4} Unix Systems | | "Think Globally, Act Locally." "Only you can make your dreams come true." | | Proud Dad of Katherine Yelena (born 8/8/89) & Robin Gregory (born 2/28/92) | ================================================================================ Archive-Date: Mon, 24 Jan 1994 20:30:09 CST Sender: LP-Mgr@SHSU.edu From: tgreen@ersys.edmonton.ab.ca (Terry Greeniaus) Reply-To: LitProg@SHSU.edu, tgreen@ERSYS.EDMONTON.AB.CA Subject: Re: Equation of two intersecting lines Message-ID: Date: Mon, 24 Jan 94 15:23:27 MST To: LitProg@SHSU.EDU gregt@math.ohio-state.edu (Greg Ferrar) writes: > In article , pdelaney@world.std.com (Peter M > Delaney) wrote: > > > > > HELP NEEDED: > > Equation determining the intersecting point for two > > straight lines. > > > > > > |<------Radius ------>| > > | | > > | | > > | | > > 1 P 2 | > > --------------+--------|------+............... > > \ . > > \ . > > \ . > > Known Values \ . > > -------------------------- \ . > > Points 1,2,3,P, and Radius \ . > > \. <-------- Intersect > > .\ of 2 line > > . \ > > . \ > > . \ > > . \ > > \ > > + 3 > > > > My problem is to find and equation that will give the Intersecting > > points of these two lines. I know Points 1,2,3 and points P. > > I also know the Radius which will intersect the lines. > > > > I have tried to derive the equation for the Intersection point, but > > my results are not correct. Can anyone tell me where I could find > > a book that would have the equation of two straight lines. > > > > I can make neither heads nor tails of the above diagram. What lines are > you finding the intersection of? What are their endpoints? What are > points 1, 2, and P? What is Radius? It looks like you might have typed > the diagram in a proportional font, which is a definite no-no, since most > of us read it in a monospaced font. > > If all you want is the interstection of two 2D lines, where you know two > points on each line, look at the FAQ. If this is not what you want, please > repost a reasonable diagram or email me directly. > > -Greg Ferrar (gregt@math.ohio-state.edu) You have to know the slope of the other line. If you knew what it was, then you would be able to figure out where they intersect. -- Terry Greeniaus tgreen@ersys.edmonton.ab.ca Edmonton Remote Systems Serving Edmonton/Northern Alberta since 1982 ================================================================================ Archive-Date: Tue, 25 Jan 1994 00:28:01 CST Sender: LP-Mgr@SHSU.edu From: rob@comp.lancs.ac.uk (Robert Lougher) Reply-To: LitProg@SHSU.edu, rob@COMP.LANCS.AC.UK Subject: Re: SGML and Literate Programming Message-ID: <1994Jan25.044620.20675@comp.lancs.ac.uk> Keywords: literate programming sgml html Date: Tue, 25 Jan 1994 04:46:20 GMT To: LitProg@SHSU.EDU In article <2hvt61$3g6@dingo.cc.uq.oz.au> coates@physics.uq.oz.au writes: >There have been a number of posts recently discussing the use of >SGML/HTML mark-up techniques in constructing Literate Programming Tools. Yes, including mine which seemed to fall on deaf ears! I believe I made a number of interesting points which haven't been picked up on. Maybe I didn't make my post as relevant to the current discussion as I could have... If you remember :-), I mentioned the system I've developed for my PhD which allows programs to be documented and browsed using hypertext (I also put in rather a lot of blurb - I am writing my thesis!). >Virtually all the current WEB tools are batch oriented, taking ASCII >sources and producing TeX output, which can later be viewed. >Batch-mode operation is common with new types of programs, avoiding >the complications of real-time interface handling, but personally I >look forward to the day when the LitProg tools will be interactive ... >... with the HTML extensions to SGML, hypertext offers interactive browsing >of code, and in principle the marked-up code should be able to be formatted >on the fly as required, I believe. In a nutshell, my system allows a program to be (re-)documented by attaching annotations to the source code using hypertext links. These can be attached to identifiers, program lines and code segments. Code segments are specified using folds. These allow a number of program lines to be grouped together and folded away. Annotations can be made on annotations and more than one link can be made to the same annotation (i.e. a graph structure). Hyper-links can also be used to browse the code, i.e. links between variable/function use and definition. This is all done in a WYSIWIG manner with windows. The code may be edited, folded and annotated interactively, and graphical views can be generated of the hypertext network. Unfortunately, to make the system language independent no formatting of the source code is performed. > >So it seems to me that on that basis, SGML/HTML markups may offer useful >advantages in generating a way of coding the literate programs so as to >be able to exploit the featrues of HTML/SGML. Still, it is clear that if >users were to be editing ASCII SGML sources, the experience might be >off-putting. I agree. >However, since SGML sources are meant to be for the machine, and in >principle SGML editors which shield the user from such source code are >suppose to be possible or even available, is the better question not >that of how well the required mark-ups for literate programming could be >added using a proper SGML editor, and what this would look like and feel >like for the end-user? When developing my system, most of the time was taken up with the development of the editor. This included issues of how should the link anchors be presented, the traversal of links, the creation of annotations, the support for browsing etc. A MAJOR consideration however, was the underlying storage. It is far easier to save the code+documentation in some unreadable format (as a word processor). This however, locks the source code into the system as it can only be modified using the editor (which may not always be available). I took the mark-up approach instead. However, rather than use a standard markup, I developed my own. This was because: a) it was 2.5 years ago b) you can develop a markup which is suited (i.e. readable) to marking up programs. HTML is angled towards standard text (i.e. lists, paragraphs etc.). I believe a markup for programs should alter the appearance of the source code as little as possible (i.e. indentation). It should be possible to edit the program occasionally in a conventional editor using the markup, or in an interactive WYSIWYG manner using the hypertext system. While my markup isn't perfect, it goes a long way to achieving that. Robert Lougher. JANET : rob@uk.ac.lancs.comp | POST: Department of Computing, Internet: rob@comp.lancs.ac.uk | University of Lancaster, Tel. : +44 524 65201 Ext. 4117 | Lancaster, LA1 4YR Fax. : +44 524 381707 | ENGLAND ================================================================================ Archive-Date: Tue, 25 Jan 1994 01:36:22 CST Sender: LP-Mgr@SHSU.edu From: jcrigler@theopolis.orl.mmc.com (Jim Crigler) Reply-To: LitProg@SHSU.edu, jcrigler@THEOPOLIS.ORL.MMC.COM Subject: Reengineering and literate programming Message-ID: <1994Jan25.051530.21338@iplmail.orl.mmc.com> Date: Tue, 25 Jan 1994 05:15:30 GMT To: LitProg@SHSU.EDU Has there been any work known to you of using literate programming as part of a reengineering effort, specifically w.r.t. documenting the existing system. (Yes I am following the thread on SGML and litprog.) Thanks for any info, Jim Crigler jcrigler@star.orl.mmc.com ================================================================================ Archive-Date: Tue, 25 Jan 1994 09:34:12 CST Sender: LP-Mgr@SHSU.edu From: coates@dingo.cc.uq.oz.au (Tony Coates) Subject: Re: Reengineering and literate programming Date: 25 Jan 1994 14:13:47 GMT Message-ID: <2i39er$dqe@dingo.cc.uq.oz.au> Reply-To: LitProg@SHSU.edu, coates@physics.uq.oz.au To: LitProg@SHSU.EDU On Tue, 25 Jan 1994 05:15:30 GMT in comp.programming.literate, Jim Crigler (jcrigler@theopolis.orl.mmc.com) wrote: : Has there been any work known to you of using literate programming as part : of a reengineering effort, specifically w.r.t. documenting the existing : system. (Yes I am following the thread on SGML and litprog.) The closest that I personally am aware of is Ross Williams' first FunnelWeb project, where he analysed and diagnosed problems in a postscript program by converting it to a literate program, adding explanations of each code section as he understood it. I suppose that this is something along the lines of what you are interested in. Ross certainly felt that using FunnelWeb in this way helped him find the problems long before other methods. Cheers, Tony. _____________________________________________________________________________ A.B.Coates, Dept. of Physics, The University of Queensland QLD 4072 Australia. Email: coates@physics.uq.oz.au Phone: (07/+617) 365-3424 Fax: (07/+617) 365-1242 Disclaimer: The University is ignorant of my opinions, let alone guilty ... _____________________________________________________________________________ ================================================================================ Archive-Date: Tue, 25 Jan 1994 12:36:15 CST Sender: LP-Mgr@SHSU.edu Date: Tue, 25 Jan 94 13:35:36 EST From: Lee Wittenberg Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET To: LitProg@shsu.edu, j_mcarthur@bix.com Subject: Re: SGML Literate Programming Message-ID: Jeffrey M\kern-.05em\raise.5ex\hbox{\b c}\kern-.05emArthur aka Jeffry McArthur writes: > Literate programming is supposed to make programs easier to understand. > Can anyone honestly say that the following is easy to understand? > > : > : #include > : > : main() { > : int i; > : for (i=0;i<10;i++) > : > : } > : I've mentioned before and feel compelled to mention again that the purpose of the web (i.e. markup) is to generate readable versions rather than to be read directly. Tangle generates a file to be read by a compiler, and weave generates a document to be read by humans. Presumably, other filters could generate stuff for other purposes. I should probably stop ranting about this, but I feel it is important. > Besides being ugly it is not even good ANSI C. There is no reason > that < and > should be used for tagging. SGML allows you to use > other characters. C/C++ programs generally only use the characters > in the range [1-127]. This leaves 128 characters in that could be > used for tag delimters. Pick any two and use them instead. Not knowing SGML, I had assumed that < and > were traditionally used (or required) for tags. If Jeffrey is right about SGML allowing other characters, then I agree with him about choosing something that doesn't interfere with programming languages. I believe that's why DEK chose @< and @>. > Personally, I prefer literate programming tools that unstand and can > pretty print the language. Me too, but I'm getting to where the free-form style of the document in noweb is more important to me than pretty-printing. On the other hand, I still dream of a filter (still notes on paper) that will pretty-print in noweb. -- Lee ================================================================================ Archive-Date: Tue, 25 Jan 1994 12:48:16 CST Sender: LP-Mgr@SHSU.edu Date: Tue, 25 Jan 94 13:47:54 EST From: Lee Wittenberg Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET To: LitProg@shsu.edu, schrod@iti.informatik.th-darmstadt.de Subject: Re: Indexing Message-ID: Joachim Schrod writes: > And, since this came up in the past in this context: Personally, I > find the idea of putting more than one module in a *WEB source and > extract them in different C++ files the most horrible thing I've ever > heard of. That goes straight against everything we need and want in > terms of software engineering. (Most of all: separation of concerns, > information hiding, introduction of abstraction levels, > encapsulation; in short, the whole concept of modularization blows > away then.) I would rather abandon Literate Programming than abandon > the things we learned about the construction of software systems the > last twenty years. Happily, it isn't necessary... I'm not going to address the main question of whether or not putting multiple modules in a single web is a Good or Bad Thing, but I would like to point out that the ability to extract chunks to a separate file is vital (IMHO) when defining C++ classes in CWEB. @ The structure of my class webs is usually something like this: @
@; // included as well as extracted @(xxx.h@>@; @@; @ With the header extracted to a separate file so the class can be used by others (using the \.{@@(}) mechanism: @(xxx.h@>= #ifndef _XXX_H #define _XXX_H // prevent re-inclusion class xxx { @@; protected: @@; public: @@; }; #endif Without the @(xxx.h@>, I wouldn't be able to make my class available in a library for other programs to use. -- Lee leew@pilot.njin.net ================================================================================ Archive-Date: Tue, 25 Jan 1994 13:17:24 CST Sender: LP-Mgr@SHSU.edu Date: Tue, 25 Jan 94 13:19:03 CST From: thompson@sun1.coe.ttu.edu (Dave Thompson (3/1/93)) Reply-To: LitProg@SHSU.edu, thompson@SUN1.COE.TTU.EDU Message-ID: <9401251919.AA22654@sun1.coe.ttu.edu> To: LitProg@SHSU.edu, coates@physics.uq.oz.au Subject: Re: Reengineering and literate programming CC: thompson@sun1.coe.ttu.edu > The closest that I personally am aware of is Ross Williams' first > FunnelWeb project, where he analysed and diagnosed problems in a postscript > program by converting it to a literate program, adding explanations of > each code section as he understood it. I've been working (off and on) on a re-engineering of a minimization algorithm. This is my exercise to learn something about literate programming from a pracitical (rather than theoretical) perspective. I'll keep track of my results, thoughts, and mistakes. Maybe there will be some interested in the outcome of my exercise? -=d ======================================================================= David B. Thompson internet: thompson@sun1.coe.ttu.edu Civil Engineering Dept. internet: dthompson@coe2.coe.ttu.edu Texas Tech University internet: wqdbt@ttacs1.ttu.edu P.O. Box 41023 Lubbock, Texas 79409-1023 "Get a haircut and get a *real* job." ======================================================================= ================================================================================ Archive-Date: Tue, 25 Jan 1994 14:37:46 CST Sender: LP-Mgr@SHSU.edu Date: Tue, 25 Jan 1994 12:36:51 -0800 (PST) From: Jerry Edens Reply-To: LitProg@SHSU.edu, jeredens@NETCOM.COM To: litprog@shsu.edu Message-ID: MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII unsubscribe ================================================================================ Archive-Date: Tue, 25 Jan 1994 16:15:47 CST Sender: LP-Mgr@SHSU.edu Date: Tue, 25 Jan 94 17:13:28 EST From: Lee Wittenberg Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET To: LitProg@shsu.edu, norman@bellcore.com Subject: Re: Indexing in Noweb Message-ID: Norman Ramsey writes (regarding the mini-identifier-indices in noweb): > I don't have a listing handy to check, but I think the numbers > of all defining chunks are listed where the identifier is listed, so > you can find both definitions. His memory is correct. Each listed identifier is followed by a list of chunk numbers where the chunk has been defined. -- Lee leew@pilot.njin.net ================================================================================ Archive-Date: Tue, 25 Jan 1994 16:15:55 CST Sender: LP-Mgr@SHSU.edu Date: Tue, 25 Jan 94 17:15:20 EST From: Lee Wittenberg Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET To: LitProg@shsu.edu, WAGNER@csearn.bitnet Subject: Re: Indexing Message-ID: > On 22 Jan 1994 16:02:37 GMT said: > >I use CWEB for "webbing" C++ programs. I would like to ask other users if they > >m > >iss the same feature as I do: > >At the end of each section, you get the references "See also Section blah blah > >. > >.." and "This code is used in Section blah blah ...". But what I really miss is > > > >that for each function call in the C++ portion of a section there should be a > >re > >ference to where the code of this function is really defined, not declared, > >that > > means something like this: > >"For the definition of function foo() see Section X.". Looking at the index > >tabl > >e at the end of the tex-output may make you search through a lot of sections > >unt > >il you find the code of a specific function. Any opinions? > > > >--- > > > >******************************************************* > >* Joachim Ziegler Universitaet des Saarlandes * > >******************************************************* > >* Though my wife still respects me I really misuse her* > >* I am having an affair with a random computer * > >* Don't you know, I'm the 2000 man * > >* And my kids they just don't understand me at all * > >* * > >* The Rolling Stones * > >******************************************************* > > > I do not see such problem. Remember that CWEB (as any WEB) enables you to > place any chunk anywhere which seems logical and convenient for you and > ctangle rearranges them so that the compiler understands the program. If > you have problems finding something in *your* programs, it only reveals that > you still think as your compiler. Try to rearrange your web file in the way > you best understand. This is one of the big advantages of LP. > > ,~~~/ /` / /| /~~~ > / / |_/ /__/ ' | / > / /~~/ /~~/ /~~/ /~~/ /\ | /| / /~~/ /~~/ /~~/ /~~/ /~~~ > / , / / /~~~ / / /~~~ / \ |/ |/ / /_/ / / / /~~~ / > ~~~~ ~~~ ~~~ ' ' ~~~ ' ` ' ' ~~~ ~~/ ' ' ~~~ ' > Zdenek Wagner______/ > > Some gateway between me and you may garble backslash. It will appear > on your screen as c due to problems with EBCDIC <--> ASCII conversion. > It has already been corrected on SOME gateways. > > The domain `.cs' does no longer exist and was replaced by `.cz'. > Valid addresses are: > > ^^ > ================================================================================ Archive-Date: Tue, 25 Jan 1994 16:42:55 CST Sender: LP-Mgr@SHSU.edu Date: Tue, 25 Jan 94 17:41:27 EST From: Lee Wittenberg Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET To: LitProg@shsu.edu, rob@comp.lancs.ac.uk Subject: Re: SGML and Literate Programming Message-ID: Robert Lougher writes: > In a nutshell, my system allows a program to be (re-)documented by attaching > annotations to the source code using hypertext links. These can be attached > to identifiers, program lines and code segments. Code segments are specified > using folds. These allow a number of program lines to be grouped together > and folded away. > > Annotations can be made on annotations and more than one link can be made > to the same annotation (i.e. a graph structure). Hyper-links can also be > used to browse the code, i.e. links between variable/function use and > definition. > > This is all done in a WYSIWIG manner with windows. The code may be edited, > folded and annotated interactively, and graphical views can be generated of > the hypertext network. Unfortunately, to make the system language independent > no formatting of the source code is performed. This all sounds very nice, but can it print out a human-readable document as well? The reason I ask is that I spent much of the last year struggling with visual programming systems where the only way to find out which bit of code was attached to an ``object'' (the system can best be described as widget-oriented rather than object-oriented, but had delusions of grandeur) was to click on the object with the mouse. Code maintenance became next to impossible, because there was no way, short of clicking on every object, to find out where variables and functions (and objects) were accessed. We solved the problem by building a ``decompiler,'' that produced a text representation of the complete program (in a home-grown mini-language), but this is not possible in all visual programming systems. The text representation was also useful when we wanted to change all the blue objects to green, or some such (we're also working on a compiler to reverse the process, but the VP system we're using is not very helpful in that regard). In any event, we can use all the lovely Unix text tools (diff, grep, etc.) to find out information about our visual programs. In any event, may I request that you include in your system some way to a) produce human-readable (typeset in some way) documents from your hypertext base, and b) produce some text version that can be analyzed by the tools we all know and love (so we don't have to go out and buy more tools :-). -- Lee leew@pilot.njin.net ================================================================================ Archive-Date: Tue, 25 Jan 1994 16:47:40 CST Sender: LP-Mgr@SHSU.edu Date: Tue, 25 Jan 94 17:47:15 EST From: Lee Wittenberg Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET To: LitProg@shsu.edu, jcrigler@theopolis.orl.mmc.com Subject: Re: Reengineering and literate programming Message-ID: Jim Crigler asks: > Has there been any work known to you of using literate programming as part > of a reengineering effort, specifically w.r.t. documenting the existing > system. (Yes I am following the thread on SGML and litprog.) Yes, Carl Gregory of Tipton Cole+Co. has been doing just that with noweb and PAL (Paradox Application language). You might want to write him direct at gregory@utkcs2.cs.utk.edu (he doesn't subscribe to this list, alas). I also rewrote a non-literate library in a CWEB version (available as eventlib under pub/leew/samples.LP at bart.kean.edu), but that was mostly a personal experiment (both wrt the LP and eventlib itself), not a system under real maintenance, so I don't guess that's what you're looking for. Then again, maybe it is. Let me know. -- Lee leew@pilot.njin.net ================================================================================ Archive-Date: Tue, 25 Jan 1994 17:45: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: Usage of multiple-output files facilities (was Re: Indexing) Date: 25 Jan 1994 22:21:37 GMT Message-ID: <2i461h$i8u@rs18.hrz.th-darmstadt.de> To: LitProg@SHSU.EDU In article , Lee Wittenberg writes: > Joachim Schrod writes: > > > And, since this came up in the past in this context: Personally, I > > find the idea of putting more than one module in a *WEB source and > > extract them in different C++ files the most horrible thing I've ever > > heard of. > > but I would > like to point out that the ability to extract chunks to a separate > file is vital (IMHO) when defining C++ classes in CWEB. I think it might be interesting to present my use of this facility, which is quite different from yours. To be more precise, the usage of our group that we built in the last ten years using a whole range of LitProg tools. The systems in question typically have resp. use between 20 and 100 modules, ranging from only 100 KB to 20 MB in total. Any comments would be appreciated. Please bear with me, I want to explain a few basic premises of our working principles first: We're in the `specification as a contract' camp. I.e., a module's specification is the document that has everything a user needs for writing his code. There must not be any need to look into the realization until binding time (where certain constraints, in particular partial implementations, run-time and space efficency, must be considered). OTOH a specification must present to an implementer everything that's needed to realize this module. In return he or she agrees to fulfill this contract. When I use a module written by another person (might have been me half a year ago ;-) I _want_ to look *only* at the specification, and I don't want to be bothered with the implementation. I want a (hopefully short and concise) description about the services this module delivers. Second, there may be more than one realization for one specification. In fact, that's quite common for most of the systems we build. Each realization has different trade-offs. I have to select the realization at configuration time, then I need a high-level description of this representation's properties. Note, that this doesn't mean access to the code; I _trust_ my fellow co-workers. After all, this trust is regularily reinforced by code reviews. Don't you remember the great Turing Award lecture by Ritchie: ``Trusting programs means trusting people''... Third, the frequency of changes to realizations is much higher than the frequency of changes to specifications. In our group that has the consequence that before anybody of us may commit a specification change to our source repository that change must be refereed by at least one other person. (We all use proper revision management, don't we? Hey, that's what my rcs style is for... ;-) ;-) That is not needed for changes in realization, where code reviews are triggered by other things. That conforms to the viewpoint that changes in design must be considered much more carefully than changes in realizations. They also concern more modules and are not local any more! Coming to C++: Like C this language does not have any notion about modules. We have to simulate them by translation units, where header file(s) represent a specification document and C++ file(s) represent the realization document. That means, *WEB coded files. One of the problems of C++ is that implementation details may sneak in the class declarations, but that can be avoided most often by well known C++ techniques. I.e., we don't find any use for implementation details in specification documents. Since a realization always has a directed [sp? `gerichtet', as in directed graphs] relationship to its specification, we think it's good style to include the specification document at the start of the realization document. After all, it's the contract that this realization fulfills. For this inclusion, we use @i (or other analogue constructs) so that it gets printed in the realization document as well. OTOH, the import in a client module is done by #include since we don't want to be overwhelmed with the information about all used modules; there are simply too many. In our method the usage for the `extract to many files' feature is mainly in the realization document. E.g., we can tangle different functions/methods to different source files, to reduce the size of the object modules. If some clients use only certain parts of a server module's protocol, smaller executables (both on disk and in memory) result if no shared libraries are available. An other example are bison/flex files. 'Though we currently switch more and more to PCCTS (Take this as an advertisement, folks! Sorry, Preston :) :) there are still old files implementing small languages where one document describing the whole language is fruitful. Well, enough musings, back to work. Hope it is of interest to some of you and might feed some discussion although it got too long... -- Joachim =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= Joachim Schrod Email: schrod@iti.informatik.th-darmstadt.de Computer Science Department Technical University of Darmstadt, Germany WEB is a very sharp sword, and novices can do things with it that make it hard for you to sleep at night. [N.Ramsey] ================================================================================ Archive-Date: Tue, 25 Jan 1994 20:47:42 CST Sender: LP-Mgr@SHSU.edu From: bart@thrain.anu.edu.au (Bart Childs) Reply-To: LitProg@SHSU.edu, bart@THRAIN.ANU.EDU.AU Subject: Re: Indexing Date: 26 Jan 1994 01:33:34 GMT Message-ID: <2i4h9e$9qv@manuel.anu.edu.au> Keywords: indexing, user responsibilities To: LitProg@SHSU.EDU Joachim Zeigler's post about indexing was responded to by Joachim Schrod. I wish to add another comment to this. There is a WEB command (@! in the original, @_ in FWEB 1.40, and I don't have a CWEB manual handy) that will underline an index entry. I am not keen on it all being automatic and find this extra burden on the author to be quite small. I believe the mindset of literate programming should be to add these commands, supplement the default index by user supplied entries, ... I think this quote is appropriate: What is written without effort is in general read without pleasure. -- Samuel Johnson The word `pleasure' could be replaced by `ease and pleasure' Bart Childs ================================================================================ Archive-Date: Tue, 25 Jan 1994 22:31:22 CST Sender: LP-Mgr@SHSU.edu From: bart@thrain.anu.edu.au (Bart Childs) Reply-To: LitProg@SHSU.edu, bart@THRAIN.ANU.EDU.AU Subject: Re: Literate programming, folding editors Date: 26 Jan 1994 01:43:51 GMT Message-ID: <2i4hsn$9r6@manuel.anu.edu.au> Keywords: editors, web-mode, outline editing To: LitProg@SHSU.EDU A web-mode is available for anonymous ftp from ftp.cs.tamu.edu It includes an adaptation of outline mode which sounds similar to folding??? Bart Childs ================================================================================ Archive-Date: Tue, 25 Jan 1994 22:37:49 CST Sender: LP-Mgr@SHSU.edu From: bart@thrain.anu.edu.au (Bart Childs) Reply-To: LitProg@SHSU.edu, bart@THRAIN.ANU.EDU.AU Subject: Re: Using WEB under DOS, Novice Date: 26 Jan 1994 02:08:02 GMT Message-ID: <2i4ja2$9sg@manuel.anu.edu.au> Keywords: DOS, novice, editors To: LitProg@SHSU.EDU In the under of Mr. Evans inquire about Using WEB under DOS, he stated that it creates well documented programs. The emphasis is a bit wrong. It ALLOWS THE AUTHOR/PROGRAMMER to create such. It is not magic, it gives the user the tools to be able to do that. Several of us at Texas A&M (my real home) have been using the DOS version of emacs (demacs) and FWEB quite successfully. It has no integration with windows! We also used the original WEB with Turbo Pascal without problem, ignoring the Turbo environment. We were using the web-mode with demacs and found it to be fine as long as the computer has plenty of memory. We used it both stand alone and on a Novell network. Minimum memory? at least 4M? I wiped out the disk installing it on a 386 with 2M. All the files we used are on ftp.cs.tamu.edu Good luck Bart CHilds ================================================================================ Archive-Date: Wed, 26 Jan 1994 00:28:22 CST Sender: LP-Mgr@SHSU.edu From: epperly@osnome.che.wisc.edu (Tom Epperly) Reply-To: LitProg@SHSU.edu, epperly@OSNOME.CHE.WISC.EDU Subject: Novice looking for literate programming language recommendations Date: 26 Jan 1994 05:41:47 GMT Message-ID: To: LitProg@SHSU.EDU I have read the FAQ which gives a nice list of literate programming tools. However, I am wondering if someone can give me some recommendations, so I can avoid having to check them all out. I am familiar with TeX, C, and C++, and I would like to start a big project using a literate programming language. Can you recommend the top two tools that I should consider? I have looked at CWEB, and it seems nice except for its method of generating multiple output files. I need to generate an include file(.h) and a C++ file(.cc), and I am not sure about the pluses and minuses of using one or two WEB files. If I want to use a single file to generate both the .h and .cc files with CWEB, it seems that the code for the .h file must be named @(filename.h@> which isn't very mneumonic to me. What are the pluses and minus of a single WEB file to generate .h and .cc? I have read the CWEB manual, and I am still not sure. Tom Epperly -- ------------------------------------------------------------------------------- Tom Epperly University of Wisconsin-Madison Chemical Engineering (608) 262-8264 epperly@osnome.che.wisc.edu Graduate Student Member of the League for Programming Freedom(fighting software monopolies) For more info contact me or lpf@uunet.uu.net. PGP public key available by finger or from public key servers. Key fingerprint = 82 25 E3 C3 A7 B3 10 59 06 B2 EC DC 63 3E 85 13 ------------------------------------------------------------------------------- ================================================================================ Archive-Date: Wed, 26 Jan 1994 07:09:16 CST Sender: LP-Mgr@SHSU.edu From: Thorbjoern Ravn Andersen Reply-To: LitProg@SHSU.edu, ravn@IMADA.OU.DK Message-ID: <199401261308.AA07289@imada.ou.dk> Subject: Re: Reengineering and literate programming To: LitProg@SHSU.edu, coates@physics.uq.oz.au Date: Wed, 26 Jan 1994 14:08:55 +0100 (MET) MIME-Version: 1.0 Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: 8bit Tony Coates | The closest that I personally am aware of is Ross Williams' first | FunnelWeb project, where he analysed and diagnosed problems in a postscript | program by converting it to a literate program, adding explanations of | each code section as he understood it. I suppose that this is something | along the lines of what you are interested in. Ross certainly felt that | using FunnelWeb in this way helped him find the problems long before | other methods. The PostScript programs I have seen were rather cryptic, and deciphering them were very much like disassembling a machinecode program which basically goes in the same lines. As I soon may be forced to write some assembly code again, but wants to limit the lack of readabillity I wish to do so in *WEB , especially because it may be handed out. Does anybody have experience with this? Regards, -- Thorbjo/rn Andersen ravn@imada.ou.dk ================================================================================ Archive-Date: Wed, 26 Jan 1994 08:34:44 CST Sender: LP-Mgr@SHSU.edu From: jmb29@cus.cam.ac.uk (Julian Birch) Reply-To: LitProg@SHSU.edu, jmb29@CUS.CAM.AC.UK Subject: Re: SGML Literate Programming Message-ID: <1994Jan26.132842.20975@infodev.cam.ac.uk> Date: Wed, 26 Jan 1994 13:28:42 GMT To: LitProg@SHSU.EDU In article Lee Wittenberg writes: > >Me too, but I'm getting to where the free-form style of the document >in noweb is more important to me than pretty-printing. On the other >hand, I still dream of a filter (still notes on paper) that will >pretty-print in noweb. > > -- Lee > I'd definitely like to see one (I'm too busy actually using noweb to write one at the moment. 8-) A problem that I see is that the markup language doesn't seem to contain any hooks for multi-language programming. (This means that any filter would probably end up formatting sh in the same manner it formatted C. Now, if someone could come up with an emacs minor mode for noweb as well, I could die happy. Julian. ================================================================================ Archive-Date: Wed, 26 Jan 1994 11:50:03 CST Sender: LP-Mgr@SHSU.edu From: maavl@cwi.nl (Marc van Leeuwen) Reply-To: LitProg@SHSU.edu, maavl@CWI.NL Subject: Re: Indexing Message-ID: Date: Wed, 26 Jan 1994 16:18:24 GMT To: LitProg@SHSU.EDU In article <2hropr$g27@rs18.hrz.th-darmstadt.de>, schrod@iti.informatik.th-darmstadt.de (Joachim Schrod) writes: |> CWEB does _not_ contain a C++ parser, so it does not know the |> difference between declaration and definition. Actually, due to the |> syntactic ambiguity of C++ this isn't easy to add, either. I have no experience with CWEB used for C++, but I think I disagree with this statement. Certainly CWEAVE contains a parser for C/C++, albeit an imprecise one that will accept more than a compiler will, and I think it in fact does distinguish between function declarations and definitions: consecutive function declarations will be simply set on consecutive lines, but in case of consecutive function definitions some white space is inserted in between (at least this is what happens in my version of CWEB). This is just to indicate that the distinction is not too difficult to make (after all, is it not just looking for an opening brace after the closing parenthesis of the parameter list?). It is true though that CWEB WEB use of the term "module" in the cited text; I prefer to speak onlyat present does not make use of the distinction: in both cases the function name will appear underlined in the index. If you want to use the information in the typeset document in sections where the function is used, you have a problem however, since parsing takes place in the same pass of CWEB where the TeX output is produced so any attempt to make this work in the current setup of CWEB would only work if the function is defined (in the CWEB source) before it is called. |> Even then, |> a pure syntactic recognition is not enough because one has to handle |> overloading and method redefinitions. (You remember, in every OO |> language you *cannot* be sure in general what function is used at a |> given place.) |> In addition, such a process would not crossref to other modules (that |> are usually implemented as other translation units in C++), you are |> stuck within one file. I think this is a much more convincing reason why it really would be a big problem. If your program is compiled from say 50 different units, each one with its own CWEB document, then many functions will appear in many indexes as "used once or more times, but nowhere defined" (because the declaration is contained in an included header file which CWEAVE does not see). [As a side note, I think a reference to the relevant #include statement from the index would note be desirable either, because the index would then be swamped with functions being defined (i.e., declared) but not used.] In any case CWEB provides no help in such situations to find the defining file; it might be useful to augment CWEB with another program that manages such global interconnections. By the way, the term "module" is used above in a way that is non-standard in WEB context (yes the word already had many meanings before WEB came around); I prefer to call that what is processed by a single run of CTANGLE or CWEAVE a single CWEB source (even if residing in more than one input file) and its result on paper a CWEB document. |> And, since this came up in the past in this context: Personally, I |> find the idea of putting more than one module in a *WEB source and |> extract them in different C++ files the most horrible thing I've ever |> heard of. That goes straight against everything we need and want in |> terms of software engineering. (Most of all: separation of concerns, |> information hiding, introduction of abstraction levels, |> encapsulation; in short, the whole concept of modularization blows |> away then.) I would rather abandon Literate Programming than abandon |> the things we learned about the construction of software systems the |> last twenty years. Happily, it isn't necessary... I suppose extracting means using the multiple file output to produce several compilation units from one CWEB source. I agree that this is a bad idea, although it is an entertaining thought to consider using multiple input files as well, each of which roughly corresponds to a translation unit; an advantage would be that CWEAVE could produce one global index. It is easy to dream up numerous disadvantages as well though, for instance the fact that keeping module names unique becomes a serious problem and that "make" would become super-conservative, recompiling the whole thing every time CTANGLE is used to update one translation unit (this is already a problem if you use multiple output files in a decent way, i.e., to generate header files, and you are honest to "make" about dependencies on header files). Marc van Leeuwen ================================================================================ Archive-Date: Wed, 26 Jan 1994 12:21:14 CST Sender: LP-Mgr@SHSU.edu Message-ID: <199401261819.NAA10057@flaubert.bellcore.com> To: LitProg@SHSU.edu, jmb29@cus.cam.ac.uk CC: ko@surya.ho.att.com Subject: Re: noweb & prettyprinting (was SGML Literate Programming) Date: Wed, 26 Jan 1994 13:19:42 -0500 From: Norman Ramsey Reply-To: LitProg@SHSU.edu, norman@BELLCORE.COM > A problem that I see is that the [noweb] markup language doesn't > seem to contain any hooks for multi-language programming. (This means that an y > filter would probably end up formatting sh in the same manner it formatted C. I have always felt that this kind of information could be provided easily on the command line. After all, the markup language doesn't contain any hooks saying what to extract, but notangle -R works just fine. I can imagine formatting a combined sh/C document using something on the order of noweave -Pfoo.c:c -Pfoo.h:c -Pfoo.sh:sh foo.nw > foo.tex and using the def-use arcs to infer the language of chunks not called <>, <>, or <>. Maybe late this year I'll get a desire to work on noweb again and build that prettyprinting tool Lee and I have been maundering about :-) I have to confess, though, that I'm more interested in automatic indexing. > Now, if someone could come up with an emacs minor mode for noweb as well, I > could die happy. Oh yes, me too! Kostas Oikonomou has done something, but it requires Lucid emacs so I haven't checked it out. Norman ================================================================================ Archive-Date: Wed, 26 Jan 1994 12:23:28 CST Sender: LP-Mgr@SHSU.edu Message-ID: <199401261821.NAA10075@flaubert.bellcore.com> To: LitProg@SHSU.edu, epperly@osnome.che.wisc.edu Subject: Re: Novice looking for literate programming language recommendations Date: Wed, 26 Jan 1994 13:21:49 -0500 From: Norman Ramsey Reply-To: LitProg@SHSU.edu, norman@BELLCORE.COM > I have read the FAQ which gives a nice list of literate programming > tools. However, I am wondering if someone can give me some > recommendations, so I can avoid having to check them all out. I am > familiar with TeX, C, and C++, and I would like to start a big project > using a literate programming language. Can you recommend the top two > tools that I should consider? Poor soul, you don't know what a flame war you're about to start. Try the Levy/Knuth CWEB, and try noweb. If you substitute nuweb for noweb, only Ross will object :-) Norman Ramsey ================================================================================ Archive-Date: Wed, 26 Jan 1994 12:29:32 CST Sender: LP-Mgr@SHSU.edu Message-ID: <199401261829.NAA10099@flaubert.bellcore.com> To: LitProg@SHSU.edu, bart@thrain.anu.edu.au Subject: Re: Indexing Date: Wed, 26 Jan 1994 13:29:08 -0500 From: Norman Ramsey Reply-To: LitProg@SHSU.edu, norman@BELLCORE.COM > There is a WEB command (@! in the original, @_ in FWEB 1.40, > and I don't have a CWEB manual handy) that will underline > an index entry. I am not keen on it all being automatic and > find this extra burden on the author to be quite small. This scheme is fine for archival code (write once, read many), but it's a problem for code that is edited frequently, because the intercalated markup distracts from the code. IMHO, the proper solution is to have an editor that hides the markup, with ``display hidden characters'' available for those rare times you need to see it. Until a righteous emacs hacker shows us how to do this, I'll continue to crusade against markup intercalated between program elements. My metacomment is that not only will many literate programs never be published, many will be read only by people who are about to modify them. In this case, having the source and document correspond wins. Norman ================================================================================ Archive-Date: Wed, 26 Jan 1994 13:30:18 CST Sender: LP-Mgr@SHSU.edu From: mauer@mcs.anl.gov (Andrew Mauer) Reply-To: LitProg@SHSU.edu, mauer@MCS.ANL.GOV Subject: Re: Novice looking for literate programming language recommendations Message-ID: Date: Wed, 26 Jan 1994 17:24:19 GMT To: LitProg@SHSU.EDU >>>>> On 26 Jan 1994 05:41:47 GMT, epperly@osnome.che.wisc.edu (Tom Epperly) said: Tom> NNTP-Posting-Host: osnome.che.wisc.edu Tom> I am familiar with TeX, C, and C++, and I would like to start a Tom> big project using a literate programming language. A caveat: literate programming is quite another beast. You will probably want to start out and experiment with some small projects (if this is feasible) to develop both your WRITING and PROGRAMMING style. In my experience, both needed changes to write decent webs (and, I admit, I still do not :-). I needed to get used to breaking things down into comfortable sections. At first the sections were *way too small*.... it was hard to understand (and maintain) because the code was too fragmented. (It was, however, impeccably documented, down to the last pebble. :-) After several months (still a novice by any measure), my document does not flow well (smoothly) between chunks. Tom> Can you recommend the top two tools that I should consider? Private email, so as not to start anything. ;-) Tom> I have looked at CWEB, and it seems nice except for its method of Tom> generating multiple output files [...] it seems that the code Tom> for the .h file must be named @(filename.h@> which isn't very Tom> mneumonic to me. This is probably not an important feature. It may be ugly, but after a few days of programming, you will have no problem with it. More important to consider is whether the tool will let you o Include other web files in your document. (Like @i.) o See the web file in the debugger, rather than the tangled file. Tom> What are the pluses and minus of a single WEB file to generate .h Tom> and .cc? (War warning...) IMHO (*very* humble O), using the same document to generate both is the way to go because it will let you keep the header defs next to the function defs (for instance), so the changes are localized if you make them. You can also weave the same informational/specification chunks into both documents. (Maybe.) However, if you're doing multiple implementations with the same interface (a la Joachim's modules), this is probably a bad way to go. [This is NOT intended as an entry into the ongoing discussion on said topic.] /Andrew/ -- /Andrew Mauer/ mauer@mcs.anl.gov ================================================================================ Archive-Date: Wed, 26 Jan 1994 13:30:26 CST Sender: LP-Mgr@SHSU.edu From: dak@tabaqui.informatik.rwth-aachen.de (David Kastrup) Reply-To: LitProg@SHSU.edu, dak@TABAQUI.INFORMATIK.RWTH-AACHEN.DE Subject: Re: Novice looking for literate programming language recommendations Date: 26 Jan 1994 18:00:56 GMT Message-ID: <2i6b4o$4jn@urmel.informatik.rwth-aachen.de> MIME-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit To: LitProg@SHSU.EDU epperly@osnome.che.wisc.edu (Tom Epperly) writes: >I have read the FAQ which gives a nice list of literate programming >tools. However, I am wondering if someone can give me some >recommendations, so I can avoid having to check them all out. I am >familiar with TeX, C, and C++, and I would like to start a big project >using a literate programming language. Can you recommend the top two >tools that I should consider? >I have looked at CWEB, and it seems nice except for its method of >generating multiple output files. I need to generate an include >file(.h) and a C++ file(.cc), and I am not sure about the pluses and >minuses of using one or two WEB files. If I want to use a single file >to generate both the .h and .cc files with CWEB, it seems that the >code for the .h file must be named @(filename.h@> which isn't very >mneumonic to me. What are the pluses and minus of a single WEB file >to generate .h and .cc? I have read the CWEB manual, and I am still >not sure. In short, modularity is always a plus. If you have independently working program files, having independent web files is a plus. Independent Modules are a bit harder to judge. Of course, cross-referencing of global variables can be a difficult task. Global variables are rather ugly, anyway, but global types can hardly be dismissed... Splitting a web into several sources is at least recommendable for development, even if you megrge them with @i into one document. Personally, I prefer noweb, since it allows making use of all LaTeX file splitting capabilities without thinking. It can also painlessly extract modules from whatever source combinations feasible, and has a very handy external command "cpif" which will compare and copy if the new version differs, touching no more files than necessary. In noweb, you'd write for the above <>= ... Or even <>= ... Although you have to quote such a filename when extracting (Extracting will extract any scrap name you choose. Using the filename is the obvious choice, except when there is only one file, where <<*>> is sufficient). Although noweb is very nice, it needs the Unix toolset (at least awk (or perl), sed, cmp, cp, some Bourne shell or clone, and a few more). nuweb is said to be similar in flavor. If you have the Unix toolset, I'd recommend looking at least at noweb, otherwise at least at nuweb (requires C compiler). They should give you a pretty good idea of a different approach (without pretty-printing). If you have to deliver C source at any stage of your project, noweb will give you a very good tangled source, either including the web as comments, or properly indented with regard to scrap indentation (as you formulated it) (I do not remember if both at the same time was possible or feasible). If you have to debug without #line directives (some environments force you to do that) you cannot do any better. -- David Kastrup dak@pool.informatik.rwth-aachen.de Tel: +49-241-72419 Fax: +49-241-79502 Goethestr. 20, D-52064 Aachen ================================================================================ Archive-Date: Wed, 26 Jan 1994 15:38:40 CST Sender: LP-Mgr@SHSU.edu Date: Wed, 26 Jan 1994 16:36:39 -0500 From: norman@bellcore.com (Norman Ramsey) Reply-To: LitProg@SHSU.edu, norman@BELLCORE.COM Message-ID: <199401262136.QAA10624@flaubert.bellcore.com> To: litprog@shsu.edu Subject: example literate program I've just gotten a literate program published in the ACM POPL conference. I have asked for an interpretation of the ACM copyright restrictions, and I have been told that there is no official interpretation, but I have been discouraged from posting the program to a newsgroup or from making it available by anonymous ftp. I can, however, mail compressed postscript to individuals. If you want a copy, send me mail and include the phrase `SEND POPL94' on the Subject: line. Norman Ramsey norman@bellcore.com ================================================================================ Archive-Date: Wed, 26 Jan 1994 16:56:42 CST Sender: LP-Mgr@SHSU.edu Message-ID: <9401262255.AA29445@MATH.ORST.EDU> To: LitProg@SHSU.edu, norman@BELLCORE.COM From: Paul Palmer Reply-To: LitProg@SHSU.edu, palmerp@MATH.ORST.EDU Subject: SEND POPL94 Date: Wed, 26 Jan 94 14:55:03 PST ================================================================================ Archive-Date: Wed, 26 Jan 1994 17:36:33 CST Sender: LP-Mgr@SHSU.edu From: glv@metronet.com (Glenn Vanderburg) Reply-To: LitProg@SHSU.edu, glv@METRONET.COM Subject: Re: Usage of multiple-output files facilities (was Re: Indexing) Date: Wed, 26 Jan 1994 20:39:02 GMT Message-ID: To: LitProg@SHSU.EDU Joachim Schrod writes: > ... we think it's >good style to include the specification document at the start of the >realization document. After all, it's the contract that this >realization fulfills. For this inclusion, we use @i (or other >analogue constructs) so that it gets printed in the realization >document as well. This is a terrific strategy. It seems to me that, when using WEB with a language like C++, it should be possible to generate two forms of printed output for a class library: the implementation, which is a fairly traditional WEB (here's what it does, and also how it works) and an interface document, which contains the detailed interface specification, along with notes on anticipated styles of use, programming idioms which it is intended to support, etc. In general, of course, I don't advocate giving someone a WEB in place of a user's manual. But for a class library, a WEB-style listing of the interface would be terrific. >OTOH, the import in a client module is done by #include since we >don't want to be overwhelmed with the information about all used >modules; there are simply too many. This is true, and it's also great that the author of the client module has a choice. Certainly, including details of all imported modules in the program would be overwhelming. But often there are one or two classes which shape the whole program; it greatly increases the readability of the program if the interfaces to those classes are presented early on. >... remember the great Turing Award lecture by Ritchie: ``Trusting >programs means trusting people''... FYI ... that was Thompson's lecture. Regards, Glenn Vanderburg ================================================================================ Archive-Date: Wed, 26 Jan 1994 18:43:12 CST Sender: LP-Mgr@SHSU.edu Date: Wed, 26 Jan 1994 19:37:19 -0500 From: norman@bellcore.com (Norman Ramsey) Reply-To: LitProg@SHSU.edu, norman@BELLCORE.COM Message-ID: <199401270037.TAA17753@flaubert.bellcore.com> To: litprog@shsu.edu Subject: indexing across source files noweb has a mechanism that makes it possible for def-use index information to refer to things in other files (see the `nodefs' command and the `-indexfrom' option to noweb). It's a hack, but it works. Of course, it's only useful if the generated .tex files are eventually \include'd in the same LaTeX document. I don't know of a way to use LaTeX to create references to another document (though doubtless something could be hacked up). This feature is useful because each source file has its own name space of chunks; only the name space of the index is unified (and that has to be done by an explicit command in a Makefile). It also has the amusing side effect of putting much less stress on TeX's memory, so it's much faster on large documents. Norman ================================================================================ Archive-Date: Wed, 26 Jan 1994 22:50:19 CST Sender: LP-Mgr@SHSU.edu From: Lim Lam Reply-To: LitProg@SHSU.edu, sci10101@LEONIS.NUS.SG Message-ID: <199401270444.MAA19095@leonis.nus.sg> Subject: unsubscribe To: litprog@SHSU.edu Date: Thu, 27 Jan 1994 12:44:02 +0800 (SST) Content-Type: text unsubscribe ================================================================================ Archive-Date: Thu, 27 Jan 1994 08:08:19 CST Sender: LP-Mgr@SHSU.edu From: N_D_Hammond Reply-To: LitProg@SHSU.edu, scindh@SNCOM1.RAESP-FARN.MOD.UK Date: Thu, 27 Jan 94 14:06:54 GMT Message-ID: <6608.9401271406@sncom1.raesp-farn.mod.uk> To: LitProg@shsu.edu Subject: FWEB problems Greetings Literati! I've just got FWEB-1.30 going, and have tried using it to typeset and generate an index for an ancient FORTRAN code we use. As a first pass, I strung all the subroutiness into one file and tried to make each subroutine a separate module within the WEB. The code's about 10,000 lines, and 77 subroutines. FWEB seemed to process about 50% without difficulty and then choked with: !!Sorry, CAPACITY EXCEEDED: Too many tokens: current number 25000, absolute max is 65536. Use command-line option "-ytw..." to override default. When I tried -ytw65536, it gave: !!Sorry, CAPACITY EXCEEDED: Too many stack levels: current number is 400, absolute max is 1000. Use command-line option "-ykw..." to override default. I can't believe that this program is *really* too big and complex, so I guess I've missed something obvious. Any ideas, suggestions, fixes etc. gratefully received. Nick Hammond ================================================================================ Archive-Date: Thu, 27 Jan 1994 09:31:11 CST Sender: LP-Mgr@SHSU.edu From: maavl@cwi.nl (Marc van Leeuwen) Reply-To: LitProg@SHSU.edu, maavl@CWI.NL Subject: Re: Novice looking for literate programming language recommendations Message-ID: Date: Thu, 27 Jan 1994 14:27:20 GMT To: LitProg@SHSU.EDU In article , epperly@osnome.che.wisc.edu (Tom Epperly) writes: |> I have looked at CWEB, and it seems nice except for its method of |> generating multiple output files. I need to generate an include |> file(.h) and a C++ file(.cc), and I am not sure about the pluses and |> minuses of using one or two WEB files. If I want to use a single file |> to generate both the .h and .cc files with CWEB, it seems that the |> code for the .h file must be named @(filename.h@> which isn't very |> mnemonic to me. First of all, the code for the .h file *does not have to be* named @(filename.h@> any more than the code for the main output file has to be unnamed. The module called @(filename.h@> just serves as the root module for shipping to that file, and it can have an arbitrary tree of submodules beneath it. (Admittedly this point is less then clear from the standard CWEB documentation). Personally I usually have a module named something like @< External typedef declarations @> and others like @< Prototypes of external functions @> and @< Macros for external use @>, but you can be more elaborate is you like. Just make sure that the names clearly indicate that this stuff is going to a header file, not to the main file. By the way, I am assuming here that header files are used just to ensure type consistency across compilation units, not as a specification mechanism; for that case a good suggestion is made in a recent posting by Joachim Schrod. Since there has been some discussion on multiple output files recently, let me elaborate this a bit with some remarks that I have missed in the discussion. You can start your CWEB source with something like @c @< Include files @> @< Local typedefs @> @< Local prototypes @> ... followed by a new module: @( myheader.h @>= @< External typedef declarations @> @< Prototypes of external functions @> ... etc. (see above) and somewhere place a definition of @< Include files @> starting like @< Include files @>= #include "myheader.h" #include ... Note that the module @( myheader.h @> is nowhere used (in contrast with the example given earlier by Lee Wittenberg; note that CWEAVE will not complain about an unused module in such a case): there is no need to clobber the main output C(++) file with a copy of the header file that can also be accessed by #include. A external function would then be introduced by code like @ Here is a useful function |do_it|. @< Prototypes of external... @>= void do_it(int now); @ @< Functions @>= void do_it(int now) { /* ... */ } This keeps the prototype right next to the function definition, and provides an easy check for the writer and the reader of the code that they do in fact match. [Incidentally, in my own version of CWEB the third line here would be written @~@< Functions @>= so as to prevent a page break in the printout after the prototype, but the control code `@~' is not known to Levy/Knuth CWEB; another extra of my version is that it will typeset the identifiers declared under @< Prototypes of external functions @> (or typedeffed in a header file by any other means) properly when they appear in other CWEB documents that include the header file. You can find my version in the FAQ under the name "CWEB 3.x", though the name may change in the near future.] |> What are the pluses and minus of a single WEB file |> to generate .h and .cc? I have read the CWEB manual, and I am still |> not sure. Concluding, if you are using header files for the purposes indicated above, I see mainly pluses. One minus is that the .h file gets written every time the main output file is regenerated by CTANGLE, and this may cause "make" to recompile any files that include it (since "make" cannot know whether the newly written header file is identical to the previously written one); this is similar (but worse) to the problem that "make" will rerun CTANGLE and recompile the C(++) file, even if you only changed the documentation part of your CWEB source. Marc van Leeuwen ================================================================================ Archive-Date: Thu, 27 Jan 1994 10:28:51 CST Sender: LP-Mgr@SHSU.edu From: fanchiot@dxcern.cern.ch (Sergio Fanchiotti) Reply-To: LitProg@SHSU.edu, fanchiot@DXCERN.CERN.CH Subject: [NOWEB 2.5a] Anybody has it working 100% under Linux? Message-ID: <1994Jan27.153051.27081@dxcern.cern.ch> Date: Thu, 27 Jan 1994 15:30:51 GMT To: LitProg@SHSU.EDU Dear Literate People, I tried getting NOWEB to run under Linux using gcc 2.4.5 , bash ( don't remember which version) and gawk (sorry forgot to write down the version of this one too). It compiles fine, it installs fine but the noweave script doesn't seem to be working that well. At first I had trouble generating the TeX source of wc.nw. This was solved changing in the script totex the auxiliary character '\n' to '\f' in the substitution of \something -> \\something. This made gawk happy (at least this kludge worked now) . But I didn't suceed in making the -index option work. Using the -index option, the thing didn't generate any output file at all. As everything works well with gcc/gawk/bash on a Sun, I suspect that it may be a problem with bash when used as a replacement for sh. Any suggestions? NOWEB is great in the simplicity area... though I don'tlike too much to depend on things like awk and sh when better alternatives like perl are out there it is something very usefull to use. In any case as it is free one shouldn't complain...too much! Thanks to it I started to grasp the idea of literate programming. If this thing doesn't run in my Linux Box, then I guess I'll have to go home to FunnelWeb :-) Thanks for any help or suggestions! Saludos, ...Sergio fanchiot@dxcern.cern.ch ================================================================================ Archive-Date: Thu, 27 Jan 1994 13:55:04 CST Sender: LP-Mgr@SHSU.edu Date: Thu, 27 Jan 94 14:53:16 EST From: Lee Wittenberg Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET To: LitProg@shsu.edu, epperly@osnome.che.wisc.edu Subject: Re: Novice looking for literate programming language recommendations Message-ID: Tom Epperly asks: > I have read the FAQ which gives a nice list of literate programming > tools. However, I am wondering if someone can give me some > recommendations, so I can avoid having to check them all out. I am > familiar with TeX, C, and C++, and I would like to start a big project > using a literate programming language. Can you recommend the top two > tools that I should consider? That's a loaded question if ever I heard one! I guess CWEB can be considered the top contender (but only because of DEK's imprimatur). Second place is up for grabs. I would vote for noweb, because that's what I use when I'm not useing CWEB, but that's just a personal choice, not a well thought-out decision. > I have looked at CWEB, and it seems nice except for its method of > generating multiple output files. I need to generate an include > file(.h) and a C++ file(.cc), and I am not sure about the pluses and > minuses of using one or two WEB files. If I want to use a single file > to generate both the .h and .cc files with CWEB, it seems that the > code for the .h file must be named @(filename.h@> which isn't very > mneumonic to me. What are the pluses and minus of a single WEB file > to generate .h and .cc? I have read the CWEB manual, and I am still > not sure. I'm quite happy using a single web to generate both the .h and the .cc (as I've mentioned before). I generally restrict myself to a single C++ class per web with the structure: @
@; @(xxx.h@>@; // simpler than a #include @@; @ @(xxx.h@>= #ifndef XXX_H #define XXX_H // prevent multiple inclusions class xxx { @@; protected: @@; public: @@; }; which works quite well (I use similar techniques in noweb, and I assume that they are available in FWEB, nuweb, etc.). The only problem is that CTANGLE assumes that its output is going to a .c file. What you have to do is use the command line ctangle xxx /dev/null xxx.cc to get the output into a .cc file (use NUL instead of /dev/null for DOS). I believe that CWEB 3.1 has a better way of doing this, but I haven't gotten around to downloading it yet. Hope this helps. -- Lee leew@pilot.njin.net ================================================================================ Archive-Date: Thu, 27 Jan 1994 14:25:26 CST Sender: LP-Mgr@SHSU.edu Date: Thu, 27 Jan 94 15:22:34 EST From: Lee Wittenberg Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET To: LitProg@shsu.edu Subject: LP and SIGCSE Message-ID: The program for the SIGCSE conference in Phoenix lists the following presentation at 2pm on Thursday, March 10: "Using Literate Programming to Teach Good Programming Practices" Stephen Shum: Augustana College; Curtis Cook: Oregon State University Anyone know anything about this? I don't believe I've seen these names in any of our discussions, but I intend to be there, anyway. Anyone else planning to show up? -- Lee leew@pilot.njin.net ================================================================================ Archive-Date: Fri, 28 Jan 1994 02:27:50 CST Sender: LP-Mgr@SHSU.edu From: norman@flaubert.bellcore.com (Norman Ramsey) Reply-To: LitProg@SHSU.edu, norman@FLAUBERT.BELLCORE.COM Subject: Re: [NOWEB 2.5a] Anybody has it working 100% under Linux? Message-ID: CC: Richard Lemieux , Sergio Fanchiotti Date: Thu, 27 Jan 1994 22:56:42 GMT To: LitProg@SHSU.EDU In article <1994Jan27.153051.27081@dxcern.cern.ch>, Sergio Fanchiotti wrote: > I tried getting NOWEB to run under Linux using gcc 2.4.5 , But I didn't suceed in making the -index option work. >Using the -index option, the thing didn't generate any output file at >all. Richard Lemieux has also complained about this one. I can't remember whether he found a solution, but I have noweb 2.5a on my linux box at home, so I'll see if I can figure it out this weekend. Norman ================================================================================ Archive-Date: Fri, 28 Jan 1994 02:27:58 CST Sender: LP-Mgr@SHSU.edu From: norman@flaubert.bellcore.com (Norman Ramsey) Reply-To: LitProg@SHSU.edu, norman@FLAUBERT.BELLCORE.COM Subject: Re: LP and SIGCSE Message-ID: Date: Fri, 28 Jan 1994 03:43:47 GMT To: LitProg@SHSU.EDU In article , Lee Wittenberg wrote: >"Using Literate Programming to Teach Good Programming Practices" >Stephen Shum: Augustana College; Curtis Cook: Oregon State University > >Anyone know anything about this? These guys wrote a paper, which I have a copy of somewhere, but their contribution wasn't entirely clear to me. The editor and referees let them get away with discussing almost zero related work, so it's pretty hard to tell what is the relationship of their stuff to anything else. ================================================================================ Archive-Date: Fri, 28 Jan 1994 02:28:24 CST Sender: LP-Mgr@SHSU.edu From: norman@flaubert.bellcore.com (Norman Ramsey) Reply-To: LitProg@SHSU.edu, norman@FLAUBERT.BELLCORE.COM Subject: Re: [NOWEB 2.5a] Anybody has it working 100% under Linux? Message-ID: CC: Richard Lemieux Date: Fri, 28 Jan 1994 03:41:14 GMT To: LitProg@SHSU.EDU >In article <1994Jan27.153051.27081@dxcern.cern.ch>, >Sergio Fanchiotti wrote: > I tried getting NOWEB to run under Linux using gcc 2.4.5 , >But I didn't suceed in making the -index option work. >Using the -index option, the thing didn't generate any output file at >all. GNU software rides again. It turns out that the noidx filter passes a very large argument to awk, and bash just silently fails. No error message, no core dump, no nothing --- just silent failure. I will patch the shell scripts to put the awk script in a temporary file and use awk -f ..., and there will be a noweb 2.5b with a fix. In the meantime you can patch it yourself, or you can switch to the Icon versions. Version 3 of noweb will be based on tcl and will have a single monolithic executable, like nuweb, without losing any of its existing flexibility. No more shell scripts, awks, seds, Icons, or any of that. Of course, nobody has volunteered to write version 3 yet... Norman ================================================================================ Archive-Date: Fri, 28 Jan 1994 04:21:59 CST Sender: LP-Mgr@SHSU.edu From: wdavid@unf6.cis.unf.edu (Bill David) Reply-To: LitProg@SHSU.edu, wdavid@UNF6.CIS.UNF.EDU Subject: Literate programming and software maintenance Message-ID: <1994Jan28.030127.10095@sinkhole.unf.edu> Date: Fri, 28 Jan 1994 03:01:27 GMT To: LitProg@SHSU.EDU Hi, I'm doing a small paper about the effects (hopefully, *benefits* ;-) ) that literate programming has when it comes to software maintenance and code reuse. I've grabbed the bibliography of the archive site, and am starting a literature search, but I'm hoping someone can give me a few useful pointers to articles on the topic. Does anyone know of anything that has been done in this area? Thanks, -Bill wdavid@unf6.cis.unf.edu ================================================================================ Archive-Date: Fri, 28 Jan 1994 06:27:00 CST Sender: LP-Mgr@SHSU.edu From: ohl@crunch.ikp.physik.th-darmstadt.de (Thorsten Ohl) Reply-To: LitProg@SHSU.edu, ohl@CRUNCH.IKP.PHYSIK.TH-DARMSTADT.DE Subject: Re: [NOWEB 2.5a] Anybody has it working 100% under Linux? Date: 28 Jan 1994 11:08:40 GMT Message-ID: To: LitProg@SHSU.EDU >>>>> "Norman" == Norman Ramsey writes: Norman> GNU software rides again. It turns out that the noidx filter Norman> passes a very large argument to awk, and bash just silently Norman> fails. No error message, no core dump, no nothing --- just Norman> silent failure. If I remember correctly, replacing gawk with the n?awk from netlib worked for me (I had to use the AT&T derived lex on my AIX box) to make the lexer ... Cheers, -tho -- /// Thorsten Ohl, TH Darmstadt, Schlossgartenstr. 9, D-64289 Darmstadt, Germany //////////////// net: ohl@crunch.ikp.physik.th-darmstadt.de, ohl@gnu.ai.mit.edu /// voice: +49-6151-16-3116, secretary: +49-6151-16-2072, fax: +49-6151-16-2421 ================================================================================ Archive-Date: Fri, 28 Jan 1994 10:25:48 CST Sender: LP-Mgr@SHSU.edu From: ceblair@ux1.cso.uiuc.edu (Charles Blair) Reply-To: LitProg@SHSU.edu, ceblair@UX1.CSO.UIUC.EDU Subject: metapost figure-drawing program? Date: 28 Jan 1994 15:01:06 GMT Message-ID: <2ib9bi$2b4@vixen.cso.uiuc.edu> To: LitProg@SHSU.EDU In Knuth's Stanford Graphbase, he used a program by John Hobby called MetaPost for the figures. He gives an ftp for the manual at att.research (I think). I've gotten the manual, but would like to know whether MetaPost itself is freely available. ================================================================================ Archive-Date: Fri, 28 Jan 1994 11:37:14 CST Sender: LP-Mgr@SHSU.edu From: yjc@po.cwru.edu (Jerome Chan) Reply-To: LitProg@SHSU.edu, yjc@PO.CWRU.EDU Subject: Revision Control in CWeb? Date: Fri, 28 Jan 1994 11:34:22 -0500 Message-ID: To: LitProg@SHSU.EDU Urm, is there any? I can't seem to find any in the CWeb docs. Maybe I'm just blind ... -- The Evil Tofu (Only Human) ================================================================================ Archive-Date: Fri, 28 Jan 1994 11:37:34 CST Sender: LP-Mgr@SHSU.edu From: tim@maths.tcd.ie (Timothy Murphy) Reply-To: LitProg@SHSU.edu, tim@MATHS.TCD.IE Subject: Re: metapost figure-drawing program? Date: 28 Jan 1994 16:04:41 -0000 Message-ID: <2ibd2p$k75@hamilton.maths.tcd.ie> To: LitProg@SHSU.EDU ceblair@ux1.cso.uiuc.edu (Charles Blair) writes: > In Knuth's Stanford Graphbase, he used a program by John Hobby >called MetaPost for the figures. He gives an ftp for the manual at >att.research (I think). I've gotten the manual, but would like to >know whether MetaPost itself is freely available. I think the position is as in the email below. I got MetaPost from AT&T after filling in their licence and waiting a _very_ long time. In fact by the time it arrived I had forgotten why I wanted it! ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ From hobby@research.att.com Wed Apr 1 03:26:23 1992 From: hobby@research.att.com Date: Tue, 31 Mar 92 12:25 EST To: postmaster@latrobe.edu.au Status: O Subject: Re: METAPOST I am the author of MetaPost. In response to your query, I am enclosing a copy of an anouncement that should be coming out soon in the TeXhax mailing list. I will post a similar item to comp.text.tex. Feel free to contact me if you would like more information. ----------------------Original Anouncement Begins Here---------------------- At the TeX User's Group Meeting in August 1989, I first announced my plans to create a picture-drawing language based on METAFONT but with PostScript output and features for dealing with text as well as graphics. By the summer of 1990, I had a preliminary version installed on a few machines here at Bell Labs, but I was not able to make it available externally. Since then, I have perfected the language implementation and the support software and I have written a User's Manual, but I had trouble getting permission to make the software available outside of AT&T. Now I can finally announce that the MetaPost language implementation is available free to any academic institution. It is still necessary to sign a non-disclosure agreement. Interested parties should contact me at the address below and give an address where I can have the necessary paperwork sent. Here are the main features of MetaPost: 1. The language is based on METAFONT and has almost the same syntax and semantics. This includes data types for curves, pictures, and linear transformations, as well as powerful macros and the ability to solve linear equations. 2. Pictures can contain typeset text using any font for which you have a .tfm file. MetaPost input can also contain text to be typeset with TeX (or troff). There are predefined macros for things like positioning labels and finding bounding boxes. 3. There are primitives and predefined macros for accessing PostScript features such as colors and shades of gray, dashed lines, and clipping, and for controlling the appearance of corners and ends of lines. While it is possible to use MetaPost to generate Type 3 PostScript fonts, the intended application is generating figures for technical documents. For this reason, MetaPost output consists of PostScript files that can be merged with TeX output using graphics inclusion features in dvi-to-PostScript translators. Since many dvi-to-PostScript translators download TeX fonts by including only those characters that are actually used by the .dvi file, extra provisions are necessary to allow such fonts in PostScript files generated via MetaPost. Version 5.47 of Tom Rokicki's dvips contains undocumented features for doing this, but a few bug-fixes are necessary to make them work properly; versions 5.481 and higher should have the feature documented and working properly. You can also use any dvi-to-PostScript program that understands encapsulated PostScript with standard comments like "%%DocumentFonts: cmr10". The actual MetaPost distribution contains web source for the translator and auxiliary programs, change files for use with the standard UNIX (r) TeX distribution (for use with web2c), auxiliary routines written in C, and a shell script that controls the preprocessing of TeX commands found in MetaPost input files. I may also include the bug fixes for dvips 5.47. John Hobby hobby@research.att.com AT&T Bell Laboratories 600 Mountain Ave. PO Box 636 Murray Hill, New Jersey 07974-0636 ------------------------------------------------------------------------ -- Timothy Murphy e-mail: tim@maths.tcd.ie tel: +353-1-2842366 s-mail: School of Mathematics, Trinity College, Dublin 2, Ireland ================================================================================ Archive-Date: Fri, 28 Jan 1994 12:36:51 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 in CWeb? Date: 28 Jan 1994 17:11:13 GMT Message-ID: <2ibgvh$svu@rs18.hrz.th-darmstadt.de> To: LitProg@SHSU.EDU In article , yjc@po.cwru.edu (Jerome Chan) writes: > Urm, is there any? I can't seem to find any in the CWeb docs. Maybe I'm > just blind ... I don't understand what you're looking for. Can you be a bit more precise? The version history of CWEB? That CWEB shall support revision control? If it's the latter: No *WEB system supports revision control, that's orthogonal to their intended purpose. Simply use CVS, Shape, or any other RC system. If you have to handle only very few files, even RCS or SCCS might be useful. In case of using CVS or RCS and using LaTeX as the markup language in one's WEB source, you might want to take a look at the rcs style that supports the better integration of RC supplied information into LaTeX. -- 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: Fri, 28 Jan 1994 13:34:01 CST Sender: LP-Mgr@SHSU.edu From: ruml@oahu.cs.ucla.edu (Wheeler Ruml) Reply-To: LitProg@SHSU.edu, ruml@OAHU.CS.UCLA.EDU Subject: Seeking K&R-style formatting for C Message-ID: <1994Jan28.181839.10400@cs.ucla.edu> Date: Fri, 28 Jan 94 18:18:39 GMT To: LitProg@SHSU.EDU I've been programming in C (and objective-c) for a while, but would like to make the switch to CWEB or a similar system. I've grown accustomed to the style of C code formatting seen in K&R, and the formatting of CWEB, although beautiful, doesn't seem to follow the same rules. After much too much work spent hacking cweave, I still don't get the exact results I want. Is there any available modification to CWEB or is there any literate C system that will give me the standard formatting for C? I would prefer a system that pretty-prints and makes indeces. Do I have to settle for a system that just passes the code "straight through" to a typewriter font? Thanks for any advice or pointers! Wheeler Ruml UCLA Mobot Lab PS - I sure it would be too much to ask that the system worked for Lisp as well... ================================================================================ Archive-Date: Fri, 28 Jan 1994 13:34:21 CST Sender: LP-Mgr@SHSU.edu From: jmb29@cus.cam.ac.uk (Julian Birch) Reply-To: LitProg@SHSU.edu, jmb29@CUS.CAM.AC.UK Subject: Re: Novice looking for literate programming language recommendations Date: 28 Jan 1994 16:08:39 GMT Message-ID: <2ibda7$50l@lyra.csi.cam.ac.uk> To: LitProg@SHSU.EDU >Tom Epperly asks: > >> I have read the FAQ which gives a nice list of literate programming >> tools. However, I am wondering if someone can give me some >> recommendations, so I can avoid having to check them all out. I am >> familiar with TeX, C, and C++, and I would like to start a big project >> using a literate programming language. Can you recommend the top two >> tools that I should consider? > Go for noweb. Consider how much time it takes to learn cweb, and then how much time it takes to learn the following: <> <>= <>+= @ Documentation @ %def list of identifiers defined in previous chunk Of course, it's a bit unix-specific, which is a pain, but it also fits the unix philosophy quite well, rather than the somewhat monolithic approach favoured elsewhere. I understand nuweb may be worth a look, but I haven't got around to it. Julian. ================================================================================ Archive-Date: Fri, 28 Jan 1994 16:37:27 CST Sender: LP-Mgr@SHSU.edu Date: Fri, 28 Jan 94 16:37:37 CST From: thompson@sun1.coe.ttu.edu (Dave Thompson (3/1/93)) Reply-To: LitProg@SHSU.edu, thompson@SUN1.COE.TTU.EDU Message-ID: <9401282237.AA28741@sun1.coe.ttu.edu> To: LitProg@SHSU.edu, jmb29@CUS.CAM.AC.UK Subject: Re: Novice looking for literate programming language recommendations > Of course, it's a bit unix-specific, which is a pain, but it also fits the > unix philosophy quite well, rather than the somewhat monolithic approach > favoured elsewhere. But, you know, Norman has already promised to change all that with the upcoming version 3.0! -=d ======================================================================= David B. Thompson internet: thompson@sun1.coe.ttu.edu Civil Engineering Dept. internet: dthompson@coe2.coe.ttu.edu Texas Tech University internet: wqdbt@ttacs1.ttu.edu P.O. Box 41023 Lubbock, Texas 79409-1023 "Get a haircut and get a *real* job." ======================================================================= ================================================================================ Archive-Date: Sat, 29 Jan 1994 20:10:22 CST Sender: LP-Mgr@SHSU.edu Date: Sat, 29 Jan 1994 21:10:02 -0500 From: norman@bellcore.com (Norman Ramsey) Reply-To: LitProg@SHSU.edu, norman@BELLCORE.COM Message-ID: <199401300210.VAA02412@flaubert.bellcore.com> To: litprog@shsu.edu Subject: personal to Eric S. Johansson Mail to esl%tuesday@leia.polaroid.com bounces. leia does *not* recognize tuesday as a valid host. Do you have an alternate address? You ought to get yourself a real DNS hostname and set up a mail exchanger through polaroid... Norman Ramsey ================================================================================ Archive-Date: Sat, 29 Jan 1994 20:57:35 CST Sender: LP-Mgr@SHSU.edu From: norman@flaubert.bellcore.com (Norman Ramsey) Reply-To: LitProg@SHSU.edu, norman@FLAUBERT.BELLCORE.COM Subject: Re: Seeking K&R-style formatting for C Message-ID: Date: 30 Jan 94 02:29:31 GMT To: LitProg@SHSU.EDU In article <1994Jan28.181839.10400@cs.ucla.edu>, Wheeler Ruml wrote: >After much too much work spent hacking cweave, I >still don't get the exact results I want. Welcome to prettyprinting. >Is there any literate >C system that will give me the standard formatting for C? There's a spiderweb grammar for C floating around somewhere, but it probably doesn't do what you want either. The sole virtue of spiderweb is that it makes this sort of hacking much easier. >Do I have to >settle for a system that just passes the code "straight through" to >a typewriter font? Gee, last I saw, that's what's in K&R :-) :-) :-) ================================================================================ Archive-Date: Sat, 29 Jan 1994 20:57:40 CST Sender: LP-Mgr@SHSU.edu From: norman@flaubert.bellcore.com (Norman Ramsey) Reply-To: LitProg@SHSU.edu, norman@FLAUBERT.BELLCORE.COM Subject: Re: Novice looking for literate programming language recommendations Message-ID: Date: Sun, 30 Jan 1994 02:26:25 GMT To: LitProg@SHSU.EDU >> [noweb is] unix-specific, which is a pain > >But, you know, Norman has already promised to change all that with the >upcoming version 3.0! I am serious about 3.0, but I am also serious when I say I doubt it will happen this year. I have commitments to four other projects this year, only three of which I expect to get to :-) My hope for version 3 is to add no new features, but to provide all the existing features (including decomposition into filters) in a single C program. I will replace all the existing sh, awk, sed, and Icon code with C code or tcl code, and I will bundle the tcl code in with the C so there will be no auxiliary files. I hope this trick will improve portability and performance, and that is will make noweb much easier to install. Norman ================================================================================ Archive-Date: Sun, 30 Jan 1994 05:10:50 CST Sender: LP-Mgr@SHSU.edu Message-ID: Date: Sun, 30 Jan 94 03:09 PST To: LitProg@SHSU.edu Subject: Re: [NOWEB 2.5a] Anybody has it working 100% under Linux? References: From: Kayvan Sylvan Reply-To: LitProg@SHSU.edu, kayvan@SATYR.SYLVAN.COM >>>>> "Norman" == Norman Ramsey writes: Norman> [...] Version 3 of noweb will be based on tcl and will have a single Norman> monolithic executable, like nuweb, without losing any of its existing Norman> flexibility. [...] nuweb may be monolithic, in the sense of "made of only one", but it's certainly not monolithic in the sense of "characterized by massiveness". On my Linux system, the length of the QMAGIC executable is ~25K. ---Kayvan | Kayvan Sylvan, Sylvan Associates, kayvan@satyr.Sylvan.COM, (408) 978-1407 | | Consulting, Training, Development, SysAdmin, {BSD,SVr3,SVr4} Unix Systems | | "Think Globally, Act Locally." "Only you can make your dreams come true." | | Proud Dad of Katherine Yelena (born 8/8/89) & Robin Gregory (born 2/28/92) | ================================================================================ Archive-Date: Sun, 30 Jan 1994 11:26:44 CST Sender: LP-Mgr@SHSU.edu From: marcus@x4u2.desy.de (Marcus Speh) Reply-To: LitProg@SHSU.edu, marcus@X4U2.DESY.DE Subject: Re: Reengineering and literate programming Message-ID: Date: Sun, 30 Jan 1994 16:44:06 GMT To: LitProg@SHSU.EDU The following describes a "reengineering", sort of - subsequent refinements of parallel code using litprog techniques. A highly readable account, IMO. Available from pobox.cscs.ch via anon FTP in Directory pub/SeRD/TechReports. Havent checked whether it is in the LitProg library, though. Regards, Marcus ----------------------------------------------------------------------------- @TECHREPORT{, NUMBER {IAM 91-018}, NOTE = {Filed: yes, PSFile: yes}, AUTHOR = {Karsten M. Decker} TITLE = { A Methodology for the Design and Implementation of Efficient Algorithms for Scalable Parallel Architectures} INSTITUTION = {Institut f\"ur Informatik}, YEAR = {1991}, TYPE = {Technical Report}, ADDRESS = {University Bern, Switzerland}, MONTH = dec, ABSTRACT = { Parallel programs exploiting as much as possible of the nominal performance of distributed memory parallel processor systems not only require efficient implementations but in particular careful algorithm design. In this paper we propose a design and implementation methodology for parallel algorithms incorporating the concept of literate programming and report on the experience gained in the development of a prototype library. The investigation is part of the SPADE project which aims at the development of an integrated program and application development environment for scientific applications on parallel architectures with distributed memory. } } ----------------------------------------------------------------------------- -- ----------------------------------------------------------------------------- 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 Email: , -- DECnet: 13313::SPEH ================================================================================ Archive-Date: Sun, 30 Jan 1994 11:42:19 CST Sender: LP-Mgr@SHSU.edu From: marcus@x4u2.desy.de (Marcus Speh) Reply-To: LitProg@SHSU.edu, marcus@X4U2.DESY.DE Subject: Re: noweb & prettyprinting (was SGML Literate Programming) Message-ID: Date: Sun, 30 Jan 1994 16:53:27 GMT To: LitProg@SHSU.EDU >>>>> "Norman" == Norman Ramsey writes: Norman> Maybe late this year I'll get a desire to work on noweb again Norman> and build that prettyprinting tool Lee and I have been Norman> maundering about :-) I have to confess, though, that I'm more Norman> interested in automatic indexing. I would like to second you on this - automatic indexing seems more wanted by novices. I gave a talk on OOP and LitProg the other day, and the index features of the FWEB samples I presented were clearly winning. After, during discussion, I had to admit that in practice I am using NOWEB and this is what I will recommend to (and set up for) physicists who are only willing to spend a small, small fraction of their time to learn a new tool... >> Now, if someone could come up with an emacs minor mode for noweb as >> well, I could die happy. Norman> Oh yes, me too! Kostas Oikonomou has done something, but it Norman> requires Lucid emacs so I haven't checked it out. I am now using folding-mode for Emacs-19 happily since a few months (thanks to c.p.l. - before I thought I knew every worthy mode... :-) - though I do miss the marvellous control I had gained over FWEB code with Child and Motl's web-mode, I think this is pretty good an intermediate solution. marcus -- ----------------------------------------------------------------------------- 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 Email: , -- DECnet: 13313::SPEH ================================================================================ Archive-Date: Sun, 30 Jan 1994 12:12:49 CST Sender: LP-Mgr@SHSU.edu From: norman@flaubert.bellcore.com (Norman Ramsey) Reply-To: LitProg@SHSU.edu, norman@FLAUBERT.BELLCORE.COM Subject: what's `monolithic' mean, and why is it interesting? Message-ID: CC: kayvan@satyr.sylvan.com Date: Sun, 30 Jan 1994 17:08:37 GMT To: LitProg@SHSU.EDU In article , Kayvan Sylvan wrote: >nuweb may be monolithic, in the sense of "made of only one", but it's >certainly not monolithic in the sense of "characterized by massiveness". No. Size is an interesting property, but it is always a question of degree. `made of only one' vs `decomposable into parts' is a difference in kind. Classic WEB is a wonderful example of a monolithic tool; it has many different features bundled into a single program, including features that have survived in no other literate-programming tool. Decomposable tools are more flexible and extensible; for example, it is easy to convert source from noweb -> CWEB because the noweb parser is separable. A nuweb -> CWEB converter would be harder (although the nuweb syntax is carefully designed, so nuweb is a lot easier to convert than other tools). An interesting litmus test for decomposability is whether the tool can be extended without recompiling. Monolithic tools are usually more portable, both because mechanisms for composing parts tend not to be portable, and also because there is less temptation to use 4 different languages to build the parts. I hope to combine the advantages of both in noweb 3.0. By shipping a single C program, I get portability. By including in that program a composition mechanism and extension language, I get decomposability and extensibility. I repeat that noweb 3.0 is vaporware, and that it won't happen in 1994. Norman ================================================================================ Archive-Date: Sun, 30 Jan 1994 12:30:29 CST Sender: LP-Mgr@SHSU.edu Date: Sun, 30 Jan 94 13:30:04 EST From: Lee Wittenberg Reply-To: LitProg@SHSU.edu, leew@PILOT.NJIN.NET To: LitProg@shsu.edu, ruml@oahu.cs.ucla.edu Subject: Re: Seeking K&R-style formatting for C Message-ID: Wheeler Ruml writes: > I've been programming in C (and objective-c) for a while, but > would like to make the switch to CWEB or a similar system. I've > grown accustomed to the style of C code formatting seen in K&R, and > the formatting of CWEB, although beautiful, doesn't seem to follow > the same rules. After much too much work spent hacking cweave, I > still don't get the exact results I want. > > Is there any available modification to CWEB or is there any literate > C system that will give me the standard formatting for C? I would > prefer a system that pretty-prints and makes indeces. Do I have to > settle for a system that just passes the code "straight through" to > a typewriter font? If you don't want to ``settle for a system that just passes the code `straigh through' to a typewriter font,'' your best (and perhaps only) bet at present is to use Spidery WEB to create your own C pretty-printing grammar (modifying the supplied one as necessary). When you've got it working, you can always retrofit the generated grammar code into CWEB, if you like. -- Lee leew@pilot.njin.net > PS - I sure it would be too much to ask that the system worked for Lisp > as well... I have a scratch Spidery grammar for Scheme. I'd be glad to send you a copy if you'd like to play with it (and, perhaps, flesh it out so that it really works). ================================================================================ Archive-Date: Mon, 31 Jan 1994 03:24:36 CST Sender: LP-Mgr@SHSU.edu From: maavl@cwi.nl (Marc van Leeuwen) Reply-To: LitProg@SHSU.edu, maavl@CWI.NL Subject: Re: Seeking K&R-style formatting for C Message-ID: Date: Mon, 31 Jan 1994 08:46:36 GMT To: LitProg@SHSU.EDU In article <1994Jan28.181839.10400@cs.ucla.edu>, ruml@oahu.cs.ucla.edu (Wheeler Ruml) writes: |> I've been programming in C (and objective-c) for a while, but |> would like to make the switch to CWEB or a similar system. I've |> grown accustomed to the style of C code formatting seen in K&R, and |> the formatting of CWEB, although beautiful, doesn't seem to follow |> the same rules. After much too much work spent hacking cweave, I |> still don't get the exact results I want. Could you be more precise about what you are missing in CWEB's formatting? Up till now I thought I thought that CWEB's way of formatting was K&R's. In fact, when I started using CWEB it actually could only typeset properly if I *wrote* K&R C (rather than ANSI) but that's fixed now. When I was developing my own version of CWEB I spent quite a bit of time making the grammar more manageable so that I could teach it some more decent formatting, in particular to break lines before opening braces rather than after them. The original style, which makes it virtually impossible to match up opening and closing braces visually, is still available under the `+u' (for ugly) option, but apparently that is still not what you want. But since the grammar includes this and other style variations based on a simple run-time rule selection scheme, it may still be instructive to study the code and maybe install your own variation; in any case the grammar rules just text strings and much more easily manipulated than in Levy/Knuth's CWEB. You can find my version at ftp.cwi.nl:pub/cweb, and it is also available from the archives (code name "CWEB 3.x"). Marc van Leeuwen ================================================================================ Archive-Date: Mon, 31 Jan 1994 06:56:28 CST Sender: LP-Mgr@SHSU.edu Date: Mon, 31 Jan 1994 13:55:52 +0100 From: cgl@risc1.rug.nl (Kees van der Laan) Reply-To: LitProg@SHSU.edu, cgl@RISC1.RUG.NL Message-ID: <9401311255.AA25178@risc1.rug.nl> To: litprog@shsu.edu Subject: norman@bellcore.com bounced, and perhaps it is of wider interest Dear Norman, I follow the lp discussion list already for quite a while and now I'm up to writing style files for (La)TeX---in TeX preferably for TeX---as literate programs meaning having the code and the documentation ---with bonus index and change file concept for descendants like tugboat.sty as basis and the proceedings styles as change files--- all to gether. From the lpfaq I got it that with TeX as programming language I need a language independent tool, and therefore I chose noweb, to start with. At the end of the faq various file formats are mentioned and hints are given what to do, however ....shar.Z is not in that list. I like examples of what to do precisely, therefore I cc-ed this message to Dave Thompson. My working environment is risc (IBM with UNIX) and the Mac, and in future I'll probably have a 486 PC. I prefer the Mac (at home) but UNIX is ok (remote). The purpose of this mail is twofold: - to inform you of what I'm up to (and perhaps I overlooked something) - to ask for hints what to do to get it (to cope with noweb-2.5.shar.Z ) install it (I read about INSTALL, but have not got it yet) Best wishes, ---Kees--- P.S. If you are interested I can email my TUGBoat BLUes paper which is the basis for looking in this direction. (32p. TeX-ed with tugboat.sty).  ================================================================================ Archive-Date: Mon, 31 Jan 1994 12:24: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: norman@bellcore.com bounced, and perhaps it is of wider interest Date: 31 Jan 1994 17:42:18 GMT Message-ID: <2ijftq$d50@rs18.hrz.th-darmstadt.de> To: LitProg@SHSU.EDU [Since this might really be of a wider interest, and since this also concerns my LitProg archive, I'll answer publicly...] In article <9401311255.AA25178@risc1.rug.nl>, cgl@risc1.rug.nl (Kees van der Laan) writes: > > At the end of the faq various file formats are mentioned and hints are given > what to do, however ....shar.Z is not in that list. Dear Kees, A `shar' file is a so-called ``shell archive.'' This is a text file, at the top of this text file you'll find directives how to unpack it. You will need a Unix system to unpack noweb (i.e., a system where Unix tools like sh, sed, awk, etc., are available). Since you also need these tools to _use_ noweb this should not be any problem... > I like examples of > what to do precisely, therefore I cc-ed this message to Dave Thompson. I would like to raise my voice **AGAINST** including such information (i.e., precise examples) into the LitProg FAQ. This is *general* information about fileformats, it has _nothing_ to do with Literate Programming. In particular, if we really want to include explanations how to unpack each and every file format (and at least 10 of them are not mentioned...) then this FAQ part will get longer than the rest. If newbies (no offense intented) really need this information, and they think that the LitProg list/newsgroup is their only source of information, one should make up a _different_ list, that can be regularly posted as well. Although I think that such a list should exist somewhere. Surely comp.binaries.* or some archivers-oriented newsgroup has this type of info. Cheers, Joachim -- =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= Joachim Schrod Email: schrod@iti.informatik.th-darmstadt.de Computer Science Department Technical University of Darmstadt, Germany ================================================================================ Archive-Date: Mon, 31 Jan 1994 18:27:27 CST Sender: LP-Mgr@SHSU.edu From: schrod@iti.informatik.th-darmstadt.de (Joachim Schrod) Reply-To: LitProg@SHSU.edu, schrod@ITI.INFORMATIK.TH-DARMSTADT.DE Subject: Contents of the LitProg Archive (monthly posting) Date: 1 Feb 1994 00:20:04 +0100 Message-ID: <2ik3n4INNfs4@spice.iti.informatik.th-darmstadt.de> To: LitProg@SHSU.EDU # literate-programming/Contents 07 Jan 94 -*- Indented-Text -*- #------------------------------------------------------------ The material available from the Literate Programming Archive is categorized, each category is put in a directory tree. While this structure (which is described in the README files) supports browsing, the need for quick access to a specific Literate Programming tool remains. This file shall assist you in this need. It presents the *WEB systems and tools available, in an alphabetic order, and names the directory where you can find it. In addition to the systems mentioned below, the LitProg Archive features texts in the directory Documentation: FAQs, papers, and an extensive bibliography in BibTeX format. Since this file is updated manually, I cannot guarantee that it's up to date. Send reports about inconsistencies of description and reality to Joachim Schrod . SYSTEM DIRECTORY REMARK ------ --------- ------ APLWEB apl w/o source, but under the GPL! [this was an error by the author] AWEB ada/aweb not supported any more cfa Tools Change File Analyzer CLiP any language, any formatter, any -- source independent wordprocessor. Hypertext -- for DOS machines/ms-dos integration possible -- for VMS machines/vms CWEB (Levy/Knuth) C++, ANSI C, K&R C -- source c.c++ -- Amiga port machines/amiga -- DOS port machines/ms-dos -- Mac port machines/mac/cweb cweb style c.c++ CWEB programs as LaTeX documents CWEB (van Leeuwen) c.c++ CWEB for ANSI C, in ANSI C CWEB (Schrod) not supported any more send me mail if you have historic interests :-) Funnelweb independent FWEB multi-lingual WEB -- source fweb -- DOS port machines/ms-dos -- MS-Windows port machines/ms-windows Knit pascal not supported any more lit2x independent [????] from Glasgow LPW machines/mac Literate Programming Workshop CAVEAT: Shareware! MapleWEB spiderweb MWEB (Schrod/Detig) modula-2 not supported any more MWEB (Sewell) modula-2 not supported any more noweb uses the UNIX toolbox paradigm -- source independent -- DOS port machines/ms-dos nuweb independent lean system, written in C ProTex independent WEB system based on TeX RWEB spiderweb for Reduce smlweb spiderweb for Standard ML SpiderWEB WEB generator, in awk -- source spiderweb -- DOS port machines/ms-dos -- OS/2 port machines/os2 -- Mac port machines/mac TIE Tools Change File Merger WEB The basis, it started with it... -- source pascal -- DOS port machines/ms-dos WEB mode Tools for GNU Emacs WinWordWEB machines/ms-dos WEB with Word for Windows Systems without support of refinements -------------------------------------- cnoweb c.c++ MAKEPROG independent is here for my own convenience :-) SchemeWEB lisp wbuild /pub/X11/other/fwf CAVEAT: Not in the LitProg Archive area! For creating new X widget classes. -- The Literate Programming Archive, or LitProg Archive for short, resides at ftp.th-darmstadt.de [130.83.55.75], directory pub/programming/literate-programming/. =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= Joachim Schrod Email: schrod@iti.informatik.th-darmstadt.de Literate Programming Archive, maintainer Technical University of Darmstadt, Germany ================================================================================ Archive-Date: Mon, 31 Jan 1994 18:27:34 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: Diff to Contents of the LitProg Archive (monthly posting) Date: 1 Feb 1994 00:20:06 +0100 Message-ID: <2ik3n6INNfs6@spice.iti.informatik.th-darmstadt.de> To: LitProg@SHSU.EDU *** /common/ftp/pub/programming/literate-programming/Contents Fri Jan 7 18:56:10 1994 --- ./Contents Sat Jan 1 00:20:07 1994 *************** *** 1,3 **** ! # literate-programming/Contents 07 Jan 94 -*- Indented-Text -*- #------------------------------------------------------------ --- 1,3 ---- ! # literate-programming/Contents 20 Dec 93 -*- Indented-Text -*- #------------------------------------------------------------ *************** *** 27,38 **** cfa Tools Change File Analyzer CLiP any language, any formatter, any ! -- source independent wordprocessor. Hypertext ! -- for DOS machines/ms-dos integration possible ! -- for VMS machines/vms CWEB (Levy/Knuth) C++, ANSI C, K&R C -- source c.c++ - -- Amiga port machines/amiga -- DOS port machines/ms-dos ! -- Mac port machines/mac/cweb cweb style c.c++ CWEB programs as LaTeX documents CWEB (van Leeuwen) c.c++ CWEB for ANSI C, in ANSI C --- 27,37 ---- cfa Tools Change File Analyzer CLiP any language, any formatter, any ! -- for DOS machines/ms-dos wordprocessor. Hypertext ! -- for VMS machines/vms integration possible ! cnoweb c.c++ CWEB (Levy/Knuth) C++, ANSI C, K&R C -- source c.c++ -- DOS port machines/ms-dos ! -- Mac port machines/mac/cweb only CTANGLE cweb style c.c++ CWEB programs as LaTeX documents CWEB (van Leeuwen) c.c++ CWEB for ANSI C, in ANSI C *************** *** 44,53 **** -- source fweb -- DOS port machines/ms-dos - -- MS-Windows port machines/ms-windows Knit pascal not supported any more lit2x independent [????] from Glasgow LPW machines/mac Literate Programming Workshop CAVEAT: Shareware! ! MapleWEB spiderweb MWEB (Schrod/Detig) modula-2 not supported any more MWEB (Sewell) modula-2 not supported any more --- 43,51 ---- -- source fweb -- DOS port machines/ms-dos Knit pascal not supported any more lit2x independent [????] from Glasgow LPW machines/mac Literate Programming Workshop CAVEAT: Shareware! ! MapleWEB maple [SpiderWEB?] MWEB (Schrod/Detig) modula-2 not supported any more MWEB (Sewell) modula-2 not supported any more *************** *** 55,62 **** -- source independent -- DOS port machines/ms-dos - nuweb independent lean system, written in C ProTex independent WEB system based on TeX ! RWEB spiderweb for Reduce ! smlweb spiderweb for Standard ML SpiderWEB WEB generator, in awk -- source spiderweb --- 53,58 ---- -- source independent -- DOS port machines/ms-dos ProTex independent WEB system based on TeX ! RWEB reduce [SpiderWEB?] SpiderWEB WEB generator, in awk -- source spiderweb *************** *** 75,83 **** -------------------------------------- - cnoweb c.c++ MAKEPROG independent is here for my own convenience :-) SchemeWEB lisp ! wbuild /pub/X11/other/fwf CAVEAT: Not in the LitProg ! Archive area! For creating ! new X widget classes. --- 71,76 ---- -------------------------------------- MAKEPROG independent is here for my own convenience :-) SchemeWEB lisp ! -- The Literate Programming Archive, or LitProg Archive for short, resides at ftp.th-darmstadt.de [130.83.55.75], directory pub/programming/literate-programming/. =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-= Joachim Schrod Email: schrod@iti.informatik.th-darmstadt.de Literate Programming Archive, maintainer Technical University of Darmstadt, Germany