home *** CD-ROM | disk | FTP | other *** search
/ Usenet 1994 January / usenetsourcesnewsgroupsinfomagicjanuary1994.iso / answers / literate-programming-faq < prev    next >
Internet Message Format  |  1993-12-25  |  33KB
  1. Path: senator-bedfellow.mit.edu!bloom-beacon.mit.edu!pad-thai.aktis.com!pad-thai.aktis.com!not-for-mail
  2. From: thompson@sun1.coe.ttu.edu
  3. Newsgroups: comp.programming.literate,comp.answers,news.answers
  4. Subject: comp.programming.literate FAQ
  5. Supersedes: <literate-programming-faq_755586014@GZA.COM>
  6. Followup-To: comp.programming.literate
  7. Date: 26 Dec 1993 00:00:25 -0500
  8. Organization: Texas Tech University, Lubbock, Texas, USA
  9. Lines: 907
  10. Sender: faqserv@security.ov.com
  11. Approved: news-answers-request@MIT.Edu
  12. Distribution: world
  13. Expires: 24 Jan 1994 05:00:13 GMT
  14. Message-ID: <literate-programming-faq_756882013@GZA.COM>
  15. Reply-To: thompson@sun1.coe.ttu.edu
  16. NNTP-Posting-Host: pad-thai.aktis.com
  17. Summary: Literate Programming FAQ--general introduction to the concepts
  18.          of literate programming and the tools available to write
  19.          literate programs.
  20. X-Last-Updated: 1993/11/11
  21. Xref: senator-bedfellow.mit.edu comp.programming.literate:833 comp.answers:3137 news.answers:16159
  22.  
  23. Archive-name: literate-programming-faq
  24. Last-modified: 1993/11/11
  25. Version: 1.0.4
  26.  
  27.  
  28. Welcome to the Literate Programming Frequently Asked Questions List
  29. -------------------------------------------------------------------
  30.  
  31. This version was created Thursday - November 11, 1993 and should
  32. considered stale after 90 days.  Information contained in this document
  33. is the best available at preparation.
  34.  
  35. Disclaimer: "This FAQ is presented with no warranties or guarantees of
  36. ANY KIND including correctness or fitness for any particular purpose.
  37. The author of this document has attempted to verify correctness of the
  38. data contained herein; however, slip-ups can and do happen.  If you use
  39. this data, you do so at your own risk."
  40.  
  41. Copyright 1993 David B. Thompson.  All rights reserved worldwide.
  42. Permission is granted to copy this document for free distribution so
  43. long as it remains intact and unmodified.
  44.  
  45.  
  46. = ======================================================================
  47.  
  48. * Introduction:
  49. ---------------
  50.  
  51. This document is for new and experienced users of literate programming
  52. tools.  The purpose is to explain the concept of literate programming and
  53. to provide a resource for locating files of interest to literate
  54. programmers and those interested in literate programming.
  55.  
  56. The Literate Programming (LitProg) Frequently Asked Questions (FAQ) list
  57. is maintained by Dave Thompson, who can be reached at:
  58.  
  59.     thompson@sun1.coe.ttu.edu     * Preferred mailing address for FAQ
  60.                                     related comments/questions.
  61.     wqdbt@ttacs1.ttu.edu          * Forwarded to my pc.
  62.  
  63. Comment and constructive criticism is welcome.  Direct flames to
  64. /dev/null (or > nul if you're a msdos user! ;-)  If you find an error,
  65. please report it.  I'm particularly interested in establishing the
  66. locations of generally available literate programming tools.  If you are
  67. the author of such a tool and wish to have it included in this list,
  68. please send email.
  69.  
  70. Please note this is a work-in-progress.  It is *not* complete, and
  71. probably will not be complete for some months.  Nevertheless, the
  72. information contained herein may be useful to some.  Use it as it is
  73. intended.
  74.  
  75. - ----------------------------------------------------------------------
  76.  
  77. - Typography:
  78. -------------
  79.  
  80. Major sections of the FAQ are divided by double lines (====).  Minor
  81. sections and other divisions are separated by single lines (----).
  82. Major topics use a "* " as a leader.  Minor topics use a "- " as a
  83. leader.  This should simplify searching for topics.
  84.  
  85.  
  86. = ======================================================================
  87.  
  88. Table of Contents:
  89. ------------------
  90.  
  91. * Introduction
  92.     - Typography.
  93. * How to get the FAQ.
  94.     - Literate Programming FAQ.
  95.     - FWEB FAQ.
  96. * The LitProg newsgroup.
  97. * Internet nodes of interest to literate programmers.
  98. * What is literate programming?
  99. * How do I begin literate programming?
  100. * What tools are available and where are they?
  101.     - c2latex
  102.     - CLip
  103.     - CWEB
  104.     - FunnelWeb
  105.     - FWEB
  106.     - noweb
  107.     - NUWEB
  108.     - SchemeWEB
  109.     - Spidery WEB
  110.     - WinWordWEB
  111. * What other resources are available?
  112.     - Virtual Coursework
  113. * Code examples.
  114.     - Examples included with developer's tools
  115.     - Cameron Smith's KR-CWEB
  116.     - Bart Child's examples for FWEB
  117. * Bibliographies.
  118. * How to anonymously ftp.
  119. * Acknowledgements.
  120. * End notes.
  121.  
  122.  
  123. = ======================================================================
  124.  
  125. * How to get the FAQ:
  126. ---------------------
  127.  
  128. - Literate Programming FAQ.
  129. ---------------------------
  130.  
  131. You have many ways to get a current copy of this FAQ.  One is to use
  132. anonymous ftp (if you don't know how, see a later section in this FAQ)
  133. to connect to one of the Comprehensive TeX Arvchive Network (CTAN) sites
  134. or the Literate Programming Archive and retrieve a copy of the file.
  135. (For more information on CTAN and the literate programming archive, see
  136. the section below entitled "Internet Nodes of Interest to Literate
  137. Programmers.")
  138.  
  139. An alternative is to use the fileserver at SHSU.  Send a message to
  140. FILESERV@SHSU.EDU (FILESERV@SHSU.BITNET) and include in your message
  141.  
  142.     SENDME FAQ.LITPROG
  143.  
  144. The file server will forward a copy of the file to you via email.
  145.  
  146.  
  147. - ----------------------------------------------------------------------
  148.  
  149. - FWEB FAQ:
  150. -----------
  151.  
  152. Marcus Speh <marcus@x4u.desy.de> maintains the FWEB FAQ.  The current
  153. version number is 1.29.  It can be retrieved in the same way as this
  154. FAQ; either by anonymous ftp or through the SHSU file server.  On the
  155. SHSU server, the file name is FAQ.FWEB.  Invoke your ftp software, open
  156. a connection to NIORD.SHSU.EDU [192.92.115.8], attach to the directory
  157. FAQ, and transfer the file FAQ.FWEB.
  158.  
  159. Alternatively, send a message to the file server, FILESERV@SHSU.EDU
  160. (FILESERV@SHSU.BITNET), and include the following text in a one line
  161. message:
  162.  
  163.     SENDME FAQ.FWEB
  164.  
  165. The file server will send the current version of the file via email.
  166.  
  167. The FWEB FAQ exists in various formats, including HyperText (see other
  168. resources below). In Europe, the complete distribution can also be
  169. obtained from ftp.desy.de [131.169.10.115] in directory
  170. /pub/faq/web/fweb/.  It is also available from the literate programming
  171. archive (LPA) in the directory LPA/documentation/faq/fweb (see the
  172. references to LPA below for more information).
  173.  
  174. = ======================================================================
  175.  
  176. * The LitProg Newsgroup:
  177. ------------------------
  178.  
  179. One of the most important resources is the literate programming
  180. newsgroup, comp.programming.literate.  You can read this newsgroup using
  181. your standard reader.  Altenatively, the newsgroup is gated to a mailing
  182. list hosted by George Greenwade and Sam Houston State University.  You
  183. can subscribe by sending mail to the list-server, LISTSERV@SHSU.EDU (or
  184. LISTSERV@SHSU.BITNET), and include in the message one line of text:
  185.  
  186.     SUBSCRIBE LITPROG  "your name in quotes"
  187.  
  188. The list is unmoderated; messages sent to litprog@shsu.edu are
  189. automatically distributed to all subscribers and cross-posted to
  190. comp.programming.literate.
  191.  
  192. Archives of the mailing list and newsgroup are maintained on
  193. niord.shsu.edu [192.92.115.8] in the directory litprog.
  194.  
  195.  
  196. = ======================================================================
  197.  
  198. * Internet Nodes of Interest to Literate Programmers:
  199. -----------------------------------------------------
  200.  
  201. The principal nodes of interest to literate programmers are the Literate
  202. Programming Archive (LPA hereafter) and the CTAN (Comprehensive TeX
  203. Archive Network).
  204.  
  205. The Literate Programming Archive (LPA) is:
  206.  
  207.   Node:       ftp.th-darmstadt.de [130.83.55.75]
  208.   Directory:  pub/programming/literate-programming
  209.   Notes:      Fastest response during off-U.S. [yep] business hours.
  210.  
  211. The CTAN sites are:
  212.  
  213. ftp host             IP            CTAN root    Institution and Sponsor
  214. -------------------------------------------------------------------------
  215. ftp.TeX.ac.UK        134.151.79.32 pub/archive  Aston Univ./UK TeX U.G.
  216. ftp.Uni-Stuttgart.DE 129.69.8.13   soft/tex     Univ. Stuttgart/DANTE e.V
  217. ftp.SHSU.edu         192.92.115.10 tex-archive  Sam Houston State Univ.
  218.  
  219. Other nodes and directories of interest include:
  220.  
  221.   Node:       niord.shsu.edu [192.92.115.8]
  222.   Directory:  various (do some snooping!)
  223.   Notes:      Has a gopher server.
  224.  
  225.   Node:       ftp.desy.de [131.169.10.115]
  226.   Directory:  pub/web. Various documents, samples, and the FWEB FAQ.
  227.   Notes:      Has a www server, http://info.desy.de:80/
  228.  
  229.  
  230. = ======================================================================
  231.  
  232. * What is Literate Programming?
  233. -------------------------------
  234.  
  235. Literate programming is the combination of documentation and source
  236. together in a fashion suited for reading by human beings.  In fact,
  237. literate programs should be enjoyable reading, even inviting!  (Sorry
  238. Bob, I couldn't resist!)  In general, literate programs combine source
  239. and documentation in a single file.  Literate programming tools then
  240. parse the file to produce either readable documentation or compilable
  241. source.  The WEB style of literate programming was created by D.E. Knuth
  242. during the development of his TeX typsetting software.
  243.  
  244. All the original work revolves around a particular literate programming
  245. tool called WEB.  Knuth says:
  246.  
  247.      The philosophy behind WEB is that an experienced system
  248.      programmer, who wants to provide the best possible
  249.      documentation of his or her software products, needs two
  250.      things simultaneously: a language like TeX for formatting,
  251.      and a language like C for programming.  Neither type of
  252.      language can provide the best documentation by itself; but
  253.      when both are appropriately combined, we obtain a system
  254.      that is much more useful than either language separately.
  255.  
  256.      The structure of a software program may be thought of as a
  257.      web that is made up of many interconnected pieces.  To
  258.      document such a program we want to explain each individual
  259.      part of the web and how it relates to its neighbours. The
  260.      typographic tools provided by TeX give us an opportunity to
  261.      explain the local structure of each part by making that
  262.      structure visible, and the programming tools provided by
  263.      languages such as C or Fortran make it possible for us to
  264.      specify the algorithms formally and unambigously. By
  265.      combining the two, we can develop a style of programming
  266.      that maximizes our ability to perceive the structure of a
  267.      complex piece of software, and at the same time the
  268.      documented programs can be mechanically translated into a
  269.      working software system that matches the documentation.
  270.  
  271.  
  272. = ======================================================================
  273.  
  274. * How to begin literate programming:
  275. ------------------------------------
  276.  
  277. A recommended book is D.E. Knuth's collection of articles (1992)
  278. "Literate Programming," Center for the Study of Language and
  279. Information, Stanford University, ISBN 0-937073-80-6 (pbk).  This book
  280. gives insight into Knuth's thoughts as he developed the web system of
  281. literate programming (and TeX for typesetting).  It does not document
  282. methods for literate programming.
  283.  
  284. A recommended book is Wayne Sewell's (1989) "Weaving a Program: Literate
  285. Programming in WEB," Van Nostrand Reinhold, ISBN 0-442-31946-0 (pbk).
  286. This book focuses on using Knuth's web system.
  287.  
  288. Some talk exists in the newsgroup/mailing list for a Usenet University
  289. course in literate programming.  I'm sure discussion of this topic will
  290. be welcomed.  If you are interested, please participate.
  291.  
  292.  
  293. = ======================================================================
  294.  
  295. * What Tools are Available:
  296. ---------------------------
  297.  
  298. A significant number of tools for literate programming are available.
  299. Most have been ported from their original systems, so support multiple
  300. computer platforms.  If you are the developer of such a tool, and would
  301. like to make the software freely available, please send me email and
  302. I'll reply with a form (like those below) for you to fill in.  (Or
  303. short-circuit the process and kludge a form from below. :-)
  304.  
  305.  
  306. - C2LaTeX:
  307. ----------
  308.  
  309. Developer:
  310.             John D. Ramsdell
  311.  
  312. System(s) supported:
  313.             Unix
  314.  
  315. Software supported:
  316.             Programming language: C.
  317.             Text formatter: LaTeX but it's easy to change the formatter.
  318.  
  319. Availability:
  320.             Anonymous ftp from
  321.                 omnigate.clarkson.edu:/pub/tex/tex-programs/c2latex.
  322.  
  323. Readme:
  324.             Absent.  Documentation is in the C source for c2latex.
  325.  
  326. Brief description:
  327.             C2latex provides simple support for literate programming
  328.             in C.  Given a C source file in which the comments have
  329.             been written in LaTeX, c2latex converts the C source file
  330.             into a LaTeX source file.  It can be used to produce
  331.             typeset listings of C programs and/or documentation
  332.             associated with the program.
  333.  
  334.             C2latex produces LaTeX source by implementing a small
  335.             number of rules.  A C comment that starts at the beginning
  336.             of a line is copied unmodified into the LaTeX source
  337.             file.  Otherwise, non-blank lines are surrounded by a pair
  338.             of formatting commands (\begin{flushleft} and
  339.             \end{flushleft}), and the lines are separated by \\*.
  340.             Each non-blank line is formatted using LaTeX's \verb
  341.             command, except comments within the line are formatted in
  342.             an \mbox.
  343.  
  344. Support:
  345.             Send bug reports to ramsdell@mitre.org.
  346.  
  347. - ----------------------------------------------------------------------
  348.  
  349. - CLip:
  350. -------
  351.  
  352. Developer:
  353.             E.W. van Ammers and M.R. Kramer
  354.  
  355. Systems supported:
  356.             Vax/VMS and MS-DOS.
  357.  
  358. Software supported:
  359.             An programming language.  Plain TeX and LaTeX text
  360.             formatters.
  361.  
  362. Availability:
  363.             Anonymous ftp from:
  364.               CTAN/web/clip
  365.               LPA/machines/ms-dos
  366.               LPA/machines/vax
  367.               sun01.info.wau.nl/CLIP
  368.  
  369.  
  370. Readme:
  371.             In distribution.
  372.  
  373. Brief description:
  374.  
  375. Support:
  376.             Unknown.
  377.  
  378.  
  379. - ----------------------------------------------------------------------
  380.  
  381. - CWEB:
  382. -------
  383.  
  384. Developer:
  385.             Silvio Levy and D.E. Knuth
  386.  
  387. System(s) supported:
  388.             Unix systems (dos and amiga ports available)
  389.  
  390. Software supported:
  391.             Languages supported are C and C++.  Text formatters are
  392.             plain TeX and LaTeX.
  393.  
  394. Availability:
  395.             anonymous ftp from:
  396.               labrea.stanford.edu/pub/cweb
  397.               LPA/c.c++
  398.               CTAN/web/c_cpp/cweb
  399.               DOS version in CTAN/web/c_cpp/cwb30p8c
  400.               DOS version in LPA/machines/ms-dos
  401.               Amiga version to be posted soon (look at CTAN).
  402.               Mac port of CTANGLE in LPA/machines/mac
  403.               LaTeX support in LPA/c.c++
  404.  
  405. Readme:
  406.             bundled with above
  407.  
  408. Brief description:
  409.  
  410. Support:
  411.             bugs to levy@math.berkeley.edu
  412.  
  413.  
  414. - ----------------------------------------------------------------------
  415.  
  416. - FunnelWeb:
  417. ------------
  418.  
  419. Developer:
  420.             Ross N. Williams: ross@guest.adelaide.edu.au
  421.  
  422. Systems supported:
  423.             MSDOS, Mac, VMS, Sun.  Other ports reported.
  424.  
  425. Software supported:
  426.             For printing, TeX.  Otherwise no restrictions.
  427.  
  428. Availability:
  429.             anonymous ftp from:
  430.               CTAN/web/funnelweb
  431.               LPA/independent
  432.               ftp.adelaide.edu.au/pub/funnelweb
  433.  
  434. Readme:
  435.             With bundle above.
  436.  
  437. Brief description:
  438.             FunnelWeb is a production-quality literate-programming tool
  439.             that emphasises simplicity and reliability. Everything about
  440.             FunnelWeb, from the simplicity of its language to the
  441.             comprehensive tutorial in the user's manual, has been
  442.             designed to make this as simple, as practical, and as usable
  443.             a tool as possible.
  444.  
  445.             Features:
  446.                + Provides a simple macro preprocessor facility.
  447.                + Can produce typeset documentation.
  448.                + Runs on Sun, VMS VAX, Macintosh, PC, and others.
  449.                + Portable C source code distributed under GNU licence.
  450.                + Comprehensive user's manual including tutorial.
  451.                + Programming-language independent.
  452.                + Can generate multiple output files.
  453.                + Allows complete control over the output text.
  454.                + Regression test suite with over 200 tests.
  455.                + Fully worked example (in /pub/funnelweb/examples).
  456.                - Requires TeX to produce typeset documentation.
  457.                - Typesets program code using TT font only.
  458.  
  459. Support:
  460.             No formal support available.  Mailing list maintained with
  461.             about 50 subscribers.  Informal assistance available from
  462.             mailing list.
  463.  
  464. - ----------------------------------------------------------------------
  465.  
  466. - FWEB:
  467. -------
  468.  
  469. Developer:
  470.             John A. Krommes
  471.  
  472. System(s) supported:
  473.             Unix and DOS platforms
  474.  
  475. Software supported:
  476.             C, C++, Fortran-77, Fortran-90, Ratfor, TeX, and LaTeX.
  477.             Text formatters are plain TeX and LaTeX.
  478.  
  479. Availability:
  480.             anonymous ftp from:
  481.               lyman.pppl.gov/pub/fweb
  482.               CTAN/web/fweb
  483.               LPA/fweb
  484.               DOS version in LPA/machines/ms-dos
  485.  
  486. Readme:
  487.             In bundle with above.
  488.  
  489. Brief description:
  490.             It also has a well-developed user's manual and its own FAQ
  491.             (see above). It runs on most platforms: VMS, PC, UNIX, and
  492.             pretty much anything that the GNU C compiler (GCC) is
  493.             supported for.
  494.  
  495. Support:
  496.             bug reports to krommes@princeton.edu
  497.  
  498. - ----------------------------------------------------------------------
  499.  
  500. - noweb:
  501. --------
  502.  
  503. Developer:
  504.             Norman Ramsey <norman@bellcore.com>
  505.  
  506. System(s) supported:
  507.             Unix and DOS platforms
  508.  
  509. Software supported:
  510.             All programming languages, plain TeX and LaTeX formatters.
  511.  
  512. Availability:
  513.             anonymous ftp from:
  514.               csservices.princeton.edu/pub/noweb.shar.Z
  515.               bellcore.com/pub/norman/noweb.shar.Z
  516.               CTAN/web/independent/noweb
  517.               LPA/independent
  518.  
  519. Readme:
  520.             with bundle above
  521.  
  522. Brief description:
  523.  
  524.             noweb is designed to meet the needs of literate programmers
  525.             while remaining as simple as possible.  Its primary
  526.             advantages are simplicity, extensibility, and
  527.             language-independence.  noweb uses 5 control sequences to
  528.             WEB's 27.  noweb now supports indexing and identifier
  529.             cross-reference.  The simple noweb manual is only 2 pages;
  530.             documenting the full power of noweave and notangle requires
  531.             another 3 pages.  noweb works ``out of the box'' with any
  532.             programming language, and its formatter-dependent part is a
  533.             60-line nawk program. The primary sacrifice relative to WEB
  534.             is the loss of prettyprinting.
  535.  
  536. Support:
  537.             by email to the author
  538.  
  539.  
  540. - ----------------------------------------------------------------------
  541.  
  542. - NUWEB:
  543. --------
  544.  
  545. Developer:
  546.             Preston Briggs: preston@cs.rice.edu
  547.  
  548. Systems supported:
  549.             Unix systems; Sparcs, RS/6000s, HPs, and (!) MSDOS.
  550.  
  551. Software supported:
  552.             It's written in C.  It works with any programming language
  553.             (or combination of programming languages) and uses Latex as
  554.             its text formatter.
  555.  
  556. Availability:
  557.             anonymous ftp from:
  558.               Unix: CTAN/web/nuweb
  559.               DOS:  CTAN/web/nuweb-pc
  560.               LPA/independent
  561.  
  562. Readme:
  563.             Send mail to preston@cs.rice.edu
  564.  
  565. Brief description:
  566.  
  567.             A single program that takes a web file written in a
  568.             combination of latex and any programming language(s) and
  569.             produces a latex file that can be pretty printed and a set
  570.             of files containing code for compilation/interpretation by
  571.             the appropriate language processors.
  572.  
  573.             Strengths include speed, simplicity, multiple languages,
  574.             nice indices and cross-references, latex.  Doesn't require
  575.             any special macros or macro files.
  576.  
  577.             Drawbacks: latex-dependent, no code pretty printing, harder
  578.             to make indices than cweb.
  579.  
  580.             More good stuff: nice support for make, doesn't reformat
  581.             source files, so they're easy to debug.  Lots of control
  582.             without too much effort.  That is, it doesn't do too much!
  583.  
  584.             Future directions... Very little change planned, except
  585.             perhaps refinements in the indexing software.
  586.  
  587. Support:
  588.             Hack it yourself or send e-mail to preston@cs.rice.edu
  589.  
  590.  
  591. - ----------------------------------------------------------------------
  592.  
  593. - SchemeWEB:
  594. ------------
  595.  
  596. Developer:
  597.             John D. Ramsdell
  598.  
  599. System(s) supported:
  600.             Unix and DOS platforms
  601.  
  602. Software supported:
  603.             Programming language: Any dialect of Lisp.
  604.             Text formatter: LaTeX.
  605.  
  606. Availability:
  607.             The Unix version is in the Scheme Repository and it is
  608.             available via anonymous ftp from:
  609.               nexus.yorku.ca/pub/scheme/utl
  610.               LPA/lisp
  611.  
  612.             The DOS version is part of the PCS/Geneva Scheme system
  613.             which is available via anonymous ftp from:
  614.               cui.unige.ch/pub/pcs.
  615.               LPA/machines/ms-dos
  616.  
  617. Readme:
  618.             In bundle with above.
  619.  
  620. Brief description:
  621.             SchemeWEB is a Unix or DOS filter that translates
  622.             SchemeWEB source into LaTeX source or Lisp source.
  623.             Lisp code is formatted in typewriter type font and
  624.             the comments are passed to LaTeX unchanged.
  625.  
  626. Support:
  627.             Send bug reports to ramsdell@mitre.org.
  628.  
  629. - ----------------------------------------------------------------------
  630.  
  631. - Spidery WEB:
  632. -------------
  633.  
  634. Developer:
  635.             Norman Ramsey <norman@bellcore.com>
  636.  
  637. System(s) supported:
  638.             Unix and DOS platforms
  639.  
  640. Software supported:
  641.             Most Algol-like languages, including C, Ada, Pascal, Awk,
  642.             and many others.  Plain TeX and latex for text formatters.
  643.  
  644. Availability:
  645.             Anonymous ftp from:
  646.                 CTAN
  647.  
  648. Readme:
  649.             In distribution.
  650.  
  651. Brief description:
  652.             A system for building language-dependent WEBs. Spider is
  653.             frozen; no further development is planned.
  654.  
  655. Support:
  656.             Bug reports to author.
  657.  
  658.  
  659. - ----------------------------------------------------------------------
  660.  
  661. - WinWordWEB:
  662. -------------
  663.  
  664. Developer:
  665.             Lee Wittenberg <leew@pilot.njin.net>
  666.  
  667. Systems supported:
  668.             Needs Microsoft Word for Windows, v.2.x, and, of course,
  669.             MS-Windows 3.x.
  670.  
  671. Software supported:
  672.             Any programming language.  Word for Windows 2.x for text
  673.             formatting and file maintenance.
  674.  
  675. Availability:
  676.             anonymous ftp from:
  677.               bart.kean.edu:pub/leew
  678.             World-Wide Web (WWW)
  679.  
  680. Readme:
  681.             WORDWEB.DOC in the downloadable package describes the
  682.             system.
  683.  
  684. Brief description:
  685.             WinWordWEB is a set of a Word for Windows macros (plus a
  686.             paragraph style) that provide a crude literate programming
  687.             environment.  The ``look and feel'' of the system is based
  688.             on Norman Ramsey's noweb, but can easily be modified to suit
  689.             individual tastes.
  690.  
  691. Support:
  692.             None.  WinWordWEB was written as a prototype to see if a
  693.             WYSIWYG literate programming system was possible.  It is
  694.             intended as a jumping off point for future work by others.
  695.             However, the system is surprisingly usable as it stands, and
  696.             the author is interested in hearing from users (satisfied
  697.             and unsatisfied).
  698.  
  699.             Anyone interested in actively supporting (and improving) the
  700.             product should contact the author via email.
  701.  
  702.  
  703. = ======================================================================
  704.  
  705. * Other resources:
  706. ------------------
  707.  
  708. An untapped resource (by me anyway ;-) is the World Wide Web.  Marcus
  709. Speh has expended considerable effort in this regard.  If you're
  710. connected to WWW, then access:
  711.  
  712.   http://info.desy.de/user/projects/LitProg.html
  713.  
  714. If you aren't connected to WWW, telnet to info.cern.ch and explore.
  715. You can reach Marcus' literate programming pages by typing:
  716.  
  717.   go http://info.desy.de/user/projects/LitProg.html
  718.  
  719. Help for people who have only Email and neither WWW nor telnet, can be
  720. obtained by Email from LISTSERV@INFO.CERN.CH by sending a message
  721. containing the command HELP.  Instructions will be returned by email.
  722. For literate programming documents, you can try anonymous ftp to
  723. ftp.desy.de [131.169.10.115] and attach to directory:
  724.  
  725.   /pub/userWWW/projects/Announce
  726.  
  727. Another resource of interest to literate programmers is the info-tex
  728. mailing list.  If you're using (La)TeX as your typsetting system and
  729. have access to internet, then you should investigate this mailing list.
  730. Mail list service is available through the SHSU list-server.  To
  731. subscribe, send a message to LISTSERV@SHSU.EDU (LISTSERV@SHSU.BITNET),
  732. and include in the message one line of text:
  733.  
  734.     SUBSCRIBE INFO-TEX "your name in quotes"
  735.  
  736. The list is unmoderated; messages sent to info-tex@shsu.edu are
  737. automatically distributed to all subscribers and cross-posted to
  738. comp.text.tex.
  739.  
  740. Archives of the mailing list and newsgroup are maintained on
  741. niord.shsu.edu [192.92.115.8] in the directory info-tex.
  742.  
  743.  
  744. - ----------------------------------------------------------------------
  745.  
  746. - Virtual Coursework:
  747. ---------------------
  748.  
  749. Marcus Speh plans an introductory course on Literate Programming on the
  750. Internet, part of the first semester of "Global Network Academy" [GNA],
  751. a non-profit corporation incorporated in the state of Texas, affilated
  752. with the Usenet University project. The texts/sample programs for this
  753. class will be made available via anonymous FTP. A special room on GNA
  754. Virtual Campus will be staffed by a consultant in one to two hour
  755. shifts.  Students with questions can telnet to the virtual campus and
  756. ask questions of the staff there. Tuition: Students should agree to work
  757. for Global Network Academy in some capacity. This may include agreeing
  758. to serve as a consultant next term, donating computing resources which
  759. belong to them, helping with programming, etc. If you are interested in
  760. registering for the course either as a student or as a consultant,
  761. please contact marcus@x4u.desy.de. You will receive a standard reply
  762. message; no further action will be taken until January 94.
  763.  
  764. [Editor's note: Because of workload, Marcus requests that email
  765. inquiries be limited to a statement of interest for either a student or
  766. consultant position until January 1994.]
  767.  
  768.  
  769. = ======================================================================
  770.  
  771. * Code Examples:
  772. ----------------
  773.  
  774. Examples of web programs are included with the FWEB, CWEB, and noweb
  775. distributions.
  776.  
  777. Cameron Smith converted the K&R calculator program into a literate
  778. program.   It can be retrieved by anonymous ftp from:
  779.   niord.shsu.edu [192.92.115.8] directory kr-cweb-sample as
  780.     krcwsamp.zip
  781.   or from
  782.     LPA/Documentation
  783.  
  784. Ross Williams has released a funnelweb example.  You can retrieve this
  785. file from node ftp.adelaide.edu.au [129.127.40.3] as
  786.   /pub/funnelweb/examples/except.*
  787. This file should be on CTAN as well.
  788.  
  789.  
  790. = ======================================================================
  791.  
  792. * Bibliographies:
  793. -----------------
  794.  
  795. Nelson Beebe has collected an extensive bibliography treating literate
  796. programming.  His work is available for anonymous ftp from
  797. ftp.math.utah.edu [128.110.198.2] in directory /pub/tex/bib as files:
  798.     litprog.bib
  799.     litprog.ltx.
  800. Although I have not verified this, LPA is an alternate source for these
  801. files.  Note that they are updated frequently (Nelson says several times
  802. each week), so be sure to get a fresh copy before extensive use.
  803. Joachim Schrod indicates that these files may be updated daily and can
  804. be retrieved via anonymous ftp at LPA/documentation.
  805.  
  806.  
  807. = ======================================================================
  808.  
  809. * How to anonymously ftp:
  810. -------------------------
  811.  
  812. Pretty much everything mentioned here is available by anonymous FTP.
  813. FAQ lists cross-posted to news.answers and rec.answers can be gotten
  814. from rtfm.mit.edu [18.70.0.209], under /pub/usenet/news.answers or under
  815. /pub/usenet/more.specific.group.name
  816.  
  817. "anonymous FTP" is just a way for files to be stored where anyone
  818. can retrieve them over the Net.    For example, to retrieve the
  819. latest version of the literate programming FAQ, do the following:
  820.  
  821. > ftp rtfm.mit.edu              /* connect to the site; message follows */
  822. > anonymous                     /* type this when it asks for your name */
  823. > <your email address>          /* type your address as the password    */
  824. > cd /pub/usenet                /* go to the directory you want to be   */
  825. > cd comp.programming.literate  /* one level down (no slash).           */
  826. > dir                           /* look at what's there                 */
  827. > get literate-progamming-faq   /* get the file; case-sensitive         */
  828. > quit                          /* stop this mysterious thing           */
  829.  
  830. If your FTP program complains that it doesn't know where the site you
  831. want to use is, type the numerical address instead of the sitename:
  832.  
  833. > ftp 18.70.0.209               /* connect with numerical address */
  834.  
  835. If you don't have ftp access, send e-mail to mail-server@rtfm.mit.edu
  836. with the single word "help" in the body of the message.
  837.  
  838. Getting binary files (executables, or any compressed files) is only
  839. slightly more difficult.   You need to set binary mode inside FTP before
  840. you transfer the file.
  841.  
  842. > binary            /* set binary transfer mode  */
  843. > ascii             /* set back to text transfer mode */
  844.  
  845. FAQs and spoiler lists are generally ascii files; everything else is
  846. generally binary files.
  847.  
  848. Some common extensions on binary files in archive sites are:
  849.  
  850.   .Z           Compressed; extract with uncompress
  851.   .tar.Z       Compressed 'tape archive'; uncompress then untar or tar -xvf
  852.   .gz or .z    Gnu gzip; use gunzip (available from prep.gnu.ai.mit.edu)
  853.   .sit         (Mac) StufIt archive
  854.   .zip         Extract with Zip or Unzip
  855.   .zoo         Yet another archive/compress program
  856.   .lhe         (Amiga) ?
  857.   .lzh         Lha archive program.
  858.   .arj         (PC) Arj archive program.
  859.   .exe         (PC) Sometimes self-extracting archives-just execute them.
  860.   .uue or .UUE Transfer as text file; use uudecode to convert to binary
  861.   .hqx         (Mac) BinHex format; transfer in text mode
  862.  
  863. Generic help can be found in the FAQs of comp.binaries.<your_system_type>
  864. for how to transfer, extract, and virus-check binary files.  (At
  865. rtfm.mit.edu)
  866.  
  867. If you can't FTP from your site, use one of the following ftp-by-mail
  868. servers:
  869.  
  870.   ftpmail@decwrl.dec.com
  871.   ftpmail@src.doc.ic.ac.uk
  872.   ftpmail@cs.uow.edu.au
  873.   ftpmail@grasp.insa-lyon.fr
  874.  
  875. For complete instructions, send a message reading "help" to the server.
  876.  
  877. If you don't know exactly what you're looking for, or exactly where it
  878. is, there are programs and servers that can help you.  For more info,
  879. send e-mail to mail-server@rtfm.mit.with with the body of the
  880. message reading send usenet/news.answers/finding-sources
  881.  
  882.  
  883. Thanks to Aliza R. Panitz (the "buglady") for this text.  I copied it
  884. verbatim from her post on faq-maintainers with only minor modifications.
  885.  
  886.  
  887. = ======================================================================
  888.  
  889. * Acknowledgements:
  890. -------------------
  891.  
  892. This document would not have happened without the help of many people.
  893. Among them are Marcus Speh, George Greenwade, Rob Beezer, Joachim
  894. Schrod, Piet van Oostrum, and Ross N. Williams.  A special thanks to
  895. Aliza R. Panitz for the text describing how to execute an anonymous ftp
  896. for files of interest.
  897.  
  898. Any omissions from these acknowledgements should be considered an act of
  899. stupidity on my part.  Of course, the authors of literate programming
  900. tools mentioned above all play a vital role in the vitality of literate
  901. programming. Furthermore, participants in the comp.programming.literate
  902. newsgroup (and associated mailing list) all contributed in various
  903. fashions. Thank all of you.
  904.  
  905.  
  906. = ======================================================================
  907.  
  908. * End notes:
  909. ------------
  910.  
  911. This document will be evolving over the next few months.  I'm planning
  912. on adding entries for additional literate programming tools and will
  913. expand the sections on examples as more examples become available. Tools
  914. I will include are web (the original pascal version), funnelweb,
  915. spiderweb, and cnoweb for starters. Others will be added as I find and
  916. document them.  Omission of a particular tool should not be considered a
  917. snub in any sense--simply an error or oversight on my part.
  918.  
  919. History:
  920.  
  921.   First release: Fri 10/15/1993 -- Yep, I finally did it!
  922.   Thu 10/21/93 -- Minor change to ftp instructions.
  923.   Fri 10/22/93 -- Minor change to stuttgart ip and fweb.faq version.
  924.                   Made reader-recommended changes, lots of re-
  925.                   organization, and added a few tools.
  926.   Mon 11/01/93 -- Corrected typo in address.
  927.   Thu 11/11/93 -- Minor change to www.
  928.  
  929. = End of File ==========================================================
  930.