Literate Programming FAQ
Contents
1. scribers and cross posted to comp text tex Archives of the mailing list and newsgroup are maintained on niord shsu edu 192 92 115 8 in the directory info tex 10 Code Examples Examples of web programs are included with the FWEB distribution Also demonstration programs are included with the CWEB distribution Bart Childs converted the K amp R calculator program into a literate program It can be retrieved from niord shsu edu 192 92 115 8 from directory kr cweb sample as kr cwsamp zip Ross Williams has released a funnelweb example You can retrieve this file from node ftp adelaide edu au 129 127 40 3 as pub funnelweb examples except This file should be on CTAN as well 11 Bibliographies Nelson Beebe has collected an extensive bibliography treat ing literate programming His work is available for an onymous ftp from ftp math utah edu 128 110 198 2 in directory pub tex bib as files litprog bib litprog ltx Although I have not verified this LPA is an alternate source for these files Note that they are updated frequently Nel son says several times each week so be sure to get a fresh copy before extensive use Joachim Schrod indicates that these files may be updated daily and can be retrieved via anonymous ftp at LPA documentation Dutch TeX Users Group NTG P O Box 394 1740 AJ Schagen The Netherlands Bijlage J 12 Howto anonymously ftp Pretty much everything mentioned here is available by anon2. ttu edu Comment and constructive criticism is welcome Direct flames to dev null or gt nul if you re a msdos user If you find an error please report it I m particularly interested in establishing the locations of generally available literate programming tools If you are the author of such a tool and wish to have it included in this list please send email Please note this is a work in progress It is not complete and probably will not be complete for some months Nev ertheless the information contained herein may be useful to some Use it as it is intended 2 Table of Contents e Introduction Typography e How to get the FAQ Literate Programming FAQ FWEB FAQ Dutch TeX Users Group NTG P O Box 394 1740 AJ Schagen The Netherlands The LitProg newsgroup Internet nodes of interest to literate programmers What is literate programming How do I begin literate programming What tools are available and where are they FWEB CWEB NOWEB NUWEB FunnelWeb SchemeWEB c2latex e Languages supported with literate programming tools e What other resources are available e Code examples Cameron Smith s KR CWEB Bart Child s examples for FWEB Examples with CWEB Examples with FWEB Bibliographies How to anonymously ftp Acknowledgements Notes 3 How to get the FAQ 3 1 Literate Programming FAQ You have many ways to get a current copy of th
3. FAQs and spoiler lists are generally ascii files everything else is generally binary files Some common extensions on binary files in archive sites are Z Compressed extract with uncompress tar Z Compressed tape archive uncompress then untar or tar xvf 2Z OF Z Gnu gzip use gunzip available from prep gnu ai mit edu sit Mac StufIt archive zip PC Extract with Zip or Unzip ZOO PC Yet another archive compress program lhe Amiga exe PC Self extracting archives just execute them uue or UUE Transfer as text file use uudecode to convert to binary hqx Mac BinHex format transfer in text mode Generic help can be found in the FAQs of comp binaries lt your_system_type gt for how to transfer extract and virus check binary files At rtfm mit edu If you can t FTP from your site use one of the following ftp by mail servers Dutch TEX Users Group NTG P O Box 394 1740 AJ Schagen The Netherlands Literate Programming FAQ 163 ftpmail decwrl dec com ftpmail srce doc ic ac uk ftpmail cs uow edu au ftpmail grasp insa lyon fr For complete instructions send a message reading help to the server If you don t know exactly what you re looking for or exactly where it is there are programs and servers that can help you For more info send e mail to mail server rtfm mit with with the body of the message reading send usenet news answers finding sources Thanks to Aliza R Panitz the
4. cui unige ch in pub pcs Readme In bundle with above Brief description SchemeWEB is a Unix or DOS filter that translates SchemeWEB source into IATEX source or Lisp source Lisp code is formatted in typewriter type font and the comments are passed to JATEX unchanged Support Send bug reports to ramsdell mitre org 8 7 C2LaTeX Developer System s supported Software supported John D Ramsdell Unix Programming language C Text formatter IATEX but it s easy to change the formatter Anonymous ftp from omnigate clarkson edu pub tex tex programs c2latex Absent Documentation is in the C source for c2latex C2latex provides simple support for literate programming in C Given a C source file in which the com ments have been written in IATEX c2latex con verts the C source file into a IATEX source file It can be used to produce typeset list ings of C programs and or documentation as sociated with the program C2latex produces IATEX source by implementing a small num ber of rules A C comment that starts at the beginning of a line is copied unmodified into the IATEX source file Otherwise non blank lines are surrounded by a pair of format ting commands begin flushleft and end flushleft and the lines are sep arated by Each non blank line is format ted using IATEX s verb command except comments within the line are formatted in an mbox Send bug reports to ramsdell mitre org Availabil
5. ftp desy de 131 169 10 38 in directory pub faq web fweb 4 The LitProg Newsgroup One of the most important resources is the literate pro gramming newsgroup comp programming literate You can read this newsgroup using your standard reader Al tenatively the newsgroup is gated to a mailing list hosted by George Greenwade and Sam Houston State University You can subscribe by sending mail to the list server LIST SERV SHSU EDU or LISTSERV SHSU BITNET and include in the message one line of text SUBSCRIBE LITPROG your name in quotes The list is unmoderated messages sent to litprog shsu edu are automatically distributed to all subscribers and cross posted to comp programming literate Archives of the mailing list and newsgroup are maintained on niord shsu edu 192 92 115 8 in the directory litprog 5 Internet Nodes of Interest to Literate Pro grammers The principal nodes of interest to literate programmers are the Literate Programming Archive LPA hereafter and the CTAN Comprehensive TEX Archive Network The Literate Programming Archive is Node ftp th darmstadt de 130 83 55 75 Directory pub programming literate programming Notes Fastest response during off U S yep business hours The CTAN sites are ftp host IP CTAN root ftp TeX ac UK 134 151 79 32 pub archive ftp Uni Stuttgart DE 129 69 1 12 soft tex ftp SHSU edu 192 92 115 10 tex archive Institution and Sponsors Aston Univ UK TE
6. Bijlage J Literate Programming FAQ 159 Literate Programming FAQ version 1 0 1 David B Thomas 15 october 93 Welcome to the Literate Programming Fre quently Asked Questions List This version was created Fri 10 15 1993 and should con sidered stale after 90 days Information contained in this document is the best available at preparation Disclaimer This FAQ is presented with no warranties or guarantees of ANY KIND including correctness or fitness for any particular purpose The author of this document has attempted to verify correctness of the data contained herein however slip ups can and do happen If you use this data you do so at your own risk Copyright 1993 David B Thompson All rights reserved Permission is granted to copy this document for free dis tribution so long as it remains intact and unmodified 1 Introduction This document is for new and experienced users of literate programming tools The purpose is to explain the concept of literate programming and to provide a resource for loc ating files of interest to literate programmers and those interested in literate programming The Literate Programming LitProg Frequently Asked Questions FAQ list is maintained by Dave Thompson who can be reached at thompson sun1 coe ttu edu Preferred mailing address for FAQ related comments questions Preferred for purposes other than FAQ Forwarded to me dthompson coe2 coe ttu edu waqdbt ttacs 1
7. X U G Univ Stuttgart DANTE e V Sam Houston State University Other nodes and directories of interest include Node niord shsu edu 192 92 115 8 Directory various do some snooping Notes Has a gopher server Node ftp desy de 131 169 10 38 Directory pub web Various documents samples and the FWEB FAQ Notes Has a www server http info desy de 80 Preprint MAPS 12 94 1 May 1994 Bijlage J 6 Whatis Literate Programming Literate programming is the combination of documentation and source together in a fashion suited for reading by hu man beings In fact literate programs should be enjoyable reading even inviting Sorry Bob I couldn t resist In general literate programs combine source and documenta tion in a single file Literate programming tools then parse the file to produce either readable documentation or com pilable source The WEB style of literate programming was created by D E Knuth during the development of his TEX typsetting software All the original work revolves around a particular literate programming tool called WEB Knuth says The philosophy behind WEB is that an experienced sys tem programmer who wants to provide the best possible documentation of his or her software products needs two things simultaneously a language like TEX for format ting and a language like C for programming Neither type of language can provide the best documentation by itself but when both are appr
8. buglady for this text I copied it verbatim from her post on faq maintainers with only minor modifications Acknowledgements This document would not have happened without the help of many people Among them are Marcus Speh George Greenwade Rob Beezer Joachim Schrod Piet van Oostrum and Ross N Williams A special thanks to Al iza R Panitz for the text describing how to execute an anonymous ftp for files of interest Any omissions from these acknowledgements should be considered an act of stupidity on my part Of course the authors of literate programming tools mentioned above all play a vital role in the vitality of literate programming Fur thermore participants in the comp programming literate newsgroup and associated mailing list all contributed in various fashions Thank all of you Notes This document will be evolving over the next few months I m planning on adding entries for additional literate pro gramming tools and will expand the sections on examples as more examples become available Tools I will include are web the original pascal version funnelweb spider web and cnoweb for starters Others will be added as I find and document them Omission of a particular tool should not be considered a snub in any sense simply an error or oversight on my part History First release Fri 10 15 1993 Yep I finally did it Preprint MAPS 12 94 1 May 1994
9. duction quality literate programming tool that emphasises simplicity and reliability Everything about FunnelWeb from the simplicity of its language to the com prehensive tutorial in the user s manual has been designed to make this as simple as practical and as usable a tool as possible Features Provides a simple macro preprocessor facility Can produce typeset documentation Runs on Sun VMS VAX Macintosh PC and others Portable C source code distributed under GNU licence Comprehensive user s manual including tutorial Programming language independent Can generate multiple output files Allows complete control over the output text Regression test suite with over 200 tests Fully worked example in pub funnelweb examples Requires TEX to produce typeset documentation Typesets program code using TT font only No formal support available Mailing list main tained with about 50 subscribers Informal as sistance available from mailing list Preprint MAPS 12 94 1 May 1994 162 8 6 SchemeWEB Developer John D Ramsdell System s supported Unix and DOS platforms Software supported Programming language Any dialect of Lisp Text formatter IATEX Availability The Unix version is in the Scheme Repository and it is available via anonymous ftp from nexus yorku ca in pub scheme utl The DOS version is part of the PCS Geneva Scheme system which is available via anonymous ftp from
10. h any thing that the GNU C compiler GCC is sup ported for bug reports to krommes princeton edu Silvio Levy and D E Knuth Unix systems dos port available C C TEX and IATEX anonymous ftp from labrea stanford edu pub cweb anonymous ftp from CTAN web c_cpp cweb anonymous ftp from CTAN web c_cpp cwb30p8c dos version bundled with above bugs to levy math berkeley edu Norman Ramsey lt norman bellcore com gt Unix and DOS platforms All programming languages formatters anonymous ftp from csservices princeton edu pub noweb shar Z anonymous ftp from bellcore com pub norman noweb shar Z with bundle above noweb is designed to meet the needs of literate programmers while remaining as simple as pos sible Its primary advantages are simplicity ex tensibility and language independence noweb uses 4 control sequences to WEB s 27 and its manual is only two pages noweb works out of the box with any programming language and its formatter dependent part is under 50 lines The primary sacrifice relative to WEB is the loss of the language dependent features prettyprinting and an index of identifiers by email to the author IA TEX Preston Briggs preston cs rice edu Unix systems Sparcs RS 6000s HPs and MSDOS It s written in C It works with any programming language or combination of programming languages and IATEX Availability Readme Brief description Support 8 5 Fu
11. is 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 Compre hensive TEX Arvchive Network CTAN sites or the literate programming archive and retrieve a copy of the file For more information on CTAN and the literate programming archive see the section below entitled Internet Nodes of Interest to Literate Programmers An alternative is to use the fileserver at SHSU Send a message to FILESERV SHSU EDU FILESERV SHSU BITNET and include in your mes sage SENDME FAQ LITPROG The file server will forward a copy of the file to you via email 3 2 FWEB FAQ Marcus Speh lt marcus x4u desy de gt maintains the FWEB FAQ It can be retrieved in the same way as this FAQ either by anonymous ftp or through the SHSU file Preprint MAPS 12 94 1 May 1994 160 Literate Programming FAQ server On the SHSU server the file name is FAQ FWEB Invoke your ftp software open a connection to NI ORD SHSU EDU 192 92 115 8 attach to the directory FAQ and transfer the file FAQ FWEB Alternatively send a message to the file server FILESERV SHSU EDU FILESERV SHSU BITNET and include the following text in a one line message SENDME FAQ FWEB The file server will send the current version of the file via email The FWEB FAQ exists in various formats including Hy perText see other resources below In Europe the com plete distribution can also be obtained from
12. ity Readme Brief description Support 9 Other resources An untapped resource by me anyway is the World Wide Web Marcus Speh has expended considerable effort in this regard If you re connected to WWW then access http info desy de pub www projects LitProg html If you aren t connected to WWW telnet to info cern ch and explore You can reach Marcus literate programming pages by typing go http info desy de pub www projects LitProg html Preprint MAPS 12 94 1 May 1994 Literate Programming FAQ Bijlage J Help for people who have only Email and neither WWW nor telnet can be obtained by Email from LIST SERV INFO CERN CH by sending a message contain ing the command HELP Instructions will be returned by email For literate programming documents you can try anonymous ftp to ftp desy de 131 169 30 33 and attach to directory pub www projects Announce Another resource of interest to literate programmers is the info tex mailing list If you re using IA T X as your typsetting system and have access to internet then you should investigate this mailing list Mail list ser vice is available through the SHSU list server To sub scribe send a message to LISTSERV SHSU EDU LIST SERV SHSU BITNET and include in the message one line of text SUBSCRIBE INFO TEX your name in quotes The list is unmoderated messages sent to info tex shsu edu are automatically distributed to all sub
13. nnelWeb Developer Systems supported Software supported Availability Readme Brief description Support Dutch TEX Users Group NTG P O Box 394 1740 AJ Schagen The Netherlands 161 anonymous ftp from CTAN web nuweb UNIX anonymous ftp from CTAN web nuweb pc MSDOS anonymous ftp from LPA Send mail to preston cs rice edu A single program that takes a web file written in a combination of IATEX and any programming language s and produces a JATRX file that can be pretty printed and a set of files containing code for compilation interpretation by the appropriate language processors Strengths include speed simplicity multiple languages nice indices and cross references IATEX Doesn t require any special macros or macro files Drawbacks IATEX dependent no code pretty printing harder to make indices than cweb More good stuff nice support for make doesn t re format source files so they re easy to debug Lots of control without too much effort That is it doesn t do too much Future directions Very little change planned except perhaps re finements in the indexing software Hack it yourself or send preston cs rice edu e mail to Ross N Williams ross guest adelaide edu au MSDOS Mac VMS Sun Other ports reported For printing TEX Otherwise no restrictions anonymous ftp from CTAN web funnelweb anonymous ftp from ftp adelaide edu pub funnelweb With bundle above FunnelWeb is a pro
14. opriately combined we obtain a system that is much more useful than either lan guage separately The structure of a software program may be thought of as a web that is made up of many interconnected pieces To document such a program we want to explain each individual part of the web and how it relates to its neigh bours The typographic tools provided by TEX give us an opportunity to explain the local structure of each part by making that structure visible and the programming tools provided by languages such as C or Fortran make it possible for us to specify the algorithms formally and unambigously By combining the two we can develop a style of programming that maximizes our ability to per ceive the structure of a complex piece of software and at the same time the documented programs can be mech anically translated into a working software system that matches the documentation 7 How to begin literate programming A recommended book is Wayne Sewell s 1989 Weaving a Program Literate Programming in WEB Van Nostrand Reinhold ISBN 0 442 31946 0 pbk Another is D E Knuth s collection of articles 1992 Lit erate Programming Center for the Study of Language and Information Stanford University ISBN 0 937073 80 6 pbk This is more of historical interest than Sewell s book but is a good read Some talk exists in the newsgroup mailing list for a Usenet University course in literate programming I m sure discu
15. s sion of this topic will be welcomed If you are interested please participate 8 What Tools are Available A significant number of tools for literate programming are available Most have been ported from their original sys tems so support multiple computer platforms If you are the developer of such a tool and would like to make the software freely available please send me email and I ll Dutch TeX Users Group NTG P O Box 394 1740 AJ Schagen The Netherlands Bijlage J Literate Programming FAQ reply with a form like those below for you to fill in Or short circuit the process and kludge a form from below 8 1 FWEB Developer System s supported Software supported Availability Readme Brief description Support 8 2 CWEB Developer System s supported Software supported Availability Readme Brief description Support 8 3 NOWEB Developer System s supported Software supported Availability Readme Brief description Support 8 4 NUWEB Developer Systems supported Software supported John A Krommes Unix and DOS platforms C C Fortran 77 Fortran 90 Ratfor TEX and JATEX anonymous ftp from lyman pppl gov pub fweb anonymous ftp from CTAN web fweb anonymous ftp from LPA machines ms dos In bundle with above It also has a well developed user s manual and its own FAQ see above It runs on most plat forms VMS PC UNIX and pretty muc
16. ymous FTP FAQ lists cross posted to news answers and rec answers can be gotten from rtfm mit edu 18 70 0 224 under pub usenet news answers or under pub usenet more specific group name anonymous FTP is just a way for files to be stored where anyone can retrieve them over the Net For example to re trieve the latest version of the literate programming FAQ do the following gt ftp rtfim mit edu connect to the site message fol lows gt anonymous type this when it asks for your name gt lt your email address gt type your address as the password K gt cd pub usenet go to the directory you want to be gt cd comp programming literate one level down no slash ay gt dir look at what s there AL gt get litprog faq get the file case sensitive gt quit stop this mysterious thing If your FTP program complains that it doesn t know where the site you want to use is type the numerical address instead of the sitename gt ftp 18 70 0 224 connect with numerical address If you don t have ftp access send e mail to mail server rtfm mit edu with the single word help in the body of the message Getting binary files executables or any compressed files is only slightly more difficult You need to set binary mode inside FTP before you transfer the file set binary transfer mode set back to text transfer mode gt binary gt ascii
Download Pdf Manuals
Related Search