Clueless literate programming questions are welcome

Good... Then I have a couple of questions: 1) Is there a FAQ? I normally read a newsgroup for more than a month before I start to question this, so... I haven't seen one posted yet... 2) Is Literate programming just a means of pretty printing and automating documentation? 3) Is there any implementations of WEB that are Macintosh compatible, OR that are machine independent and will run with PERL or some other widely available language? 4) I have noticed several WEB thingies are C, C++, Pascal... literate(?) but never have I seen the word Smalltalk... anyone? How's that?

There is. The last one I have was dated May 27, so perhaps it's no longer maintained (or perhaps I just haven't saved it for a while). Try rtfm.mit.edu.

No. At least in my view, literate programming is a mechanism for writing programs which are relatively easy to maintain. Apart from encouraging verbose comments, literate programming places emphasis on explaining how and why a program was written the way it was, and it provides a mechanism for laying the program out in a way which will best aid understanding. A potential side-benefit of this is that the literate programmer has to think twice about everything, which can help uncover problems before they get into production systems and lead to the end of civilization.

There's an MPW literate programming tool, which I suppose is in the archive at Darmstadt. I don't really know what languages or formatters it supports, and the Mac programmers where I work were not in any way interested in it :(.

There are a few packages that don't worry about the source code. FunnelWeb, noweb and nuweb come to mind.

Noweb, nuweb, and FunnelWeb will let you write programs in any language. I think nuweb just works on Macs. Getting noweb installed on a Mac would be quite a chore.

(Al)ProTex provides another alternative, if you have (La)TeX on your system. No installation is required besides ftp'ing two files.

Trygve Reenskaug and Anne L. Skaar. An Environment for Literate Smalltalk Programming. Proceedings of the 1989 Conference on Object-Oriented Programming: Systems, Languages, and Applications, ACM SIGPLAN Notices 24:10 (1989), 337--345.

[I haven't seen the original posting, so I am responding here.] Currently available for Macs (excerpt from the README) at the LitProg Archive (see below) in machines/mac/. I welcome more contributions.

    CWEB                - port of CWEB
    Impact              - CTANGLE with Apple-events
    LPW                 - Literate Programming Workshop
                          ATTENTION: This is shareware!  [50 US-$]
    *SpiderWEB*         - port of SpiderWEB, for MPW

It's the program documentation which sits in the same file, not (necessarily) the user's documentation. The purpose is clear: by having the code and code comments appear at the same place, it is psychologically more annoying to have them disagree, so docs and code tend to be more in sync. Also, being able to explain each code part as a separate entity, even if it is not a function, is a definite plus. Especially for programs for mathematical purposes, it is often handy to be able to use all the capabilities for formulas your typesetting system supports in comments. But I am babbling. See the FAQ which is posted on a frequent basis here.

------------------ example of a latex file ---------------------

% Requires LaTeX, (Al)ProTex,  the file `noweb.sty' from 
% bellcore.com : pub/norman/noweb/TeX/         and the following files from
% bellcore.com : pub/norman/noweb/examples/
%
%    breakmodel.nw      dag.nw        graphs.nw     mipscoder.nw
%    multicol.sty       primes.nw     scanner.nw    test.nw
%    tree.nw            wc.bbl        wc.nw         README
%
% Changes needed within the `.nw' files
%  
% 1. Insert `@' after each chunk that is not delimited with such a character
% 2. Replace `@<<' with `<@<'
% 3. Clean ``[[...]]'' from special characters that differ from ^ and _

\documentstyle{book}

%-----------  ProTeX adjusted to accept noweb inputs -------

\input ProTex.sty    \catcode`\^^M=13  \def\CodeDel{{=}{
                                       @}}                \catcode`\^^M=5
\AlProTex{any,<<<>>>,title,list,ClearCode,_^,ShowFile,[]}

\let\oldModifyAppendCode=\ModifyAppendCode
\let\oldModifyOutputCode=\ModifyOutputCode
\def\ModifyAppendCode#1{\oldModifyAppendCode{#1}\catcode`\<=13
                                                \catcode`\\=12\relax}
\def\alprotextitle#1#2>>{\egroup \<#2\>}
\def\alprotextitleA#1#2>>{\<#2\>}
\def\ltsym{<    \catcode`\<=13
\def<#1{\ifx#1<\bgroup \catcode`\$=12 \catcode`\\=12  \par
    \expandafter\alprotextitle  \else  \expandafter\ltapsym\fi #1}
\def\ltapsym#1{\ltsym\ifx#1@\else\expandafter#1\fi}
\def\ModifyOutputCode{\def<##1{\ifx##1<\expandafter\alprotextitleA 
           \else  \expandafter\ltapsym\fi ##1}\oldModifyOutputCode}

%-------------------------------------------------

\textwidth=6.9in
\oddsidemargin=0pt
\evensidemargin=0pt

\begin{document}  \tableofcontents

%---------- noweb style files --------------------

\catcode`\@=11     \catcode`\^=7   \input multicol.sty   \input noweb.sty   
\catcode`\@=12     \catcode`\^=13     

%-------------- tame  [[...]] --------------------

\def\oldcite{\@tempswafalse \@citex []}   \def\bracket{[}   \catcode`\[=13
\def[{\bracket}
\def\cite{\@ifnextchar [{\@tempswatrue \@citex }{\oldcite}}

%---------------- README -------------------------

\chapter{README}  \ShowFile{README}

       \let\oldinput=\input
       \def\input#1.#2 {\chapter{#1}\openin15=#1.#2
          \ifeof15 \closein15  
             \immediate\write16{-----File ``#1.#2'' is missing-----}
          \else \oldinput #1.#2 \fi}

%---------------- breakmodel ---------------------

\input breakmodel.nw                                    \ClearCode

%----------------- dag ---------------------------

\input dag.nw
<<dag>>=
<<*>>
@                           \OutputCode\<ag\>          \ClearCode

%----------------- graphs ------------------------

                      \begingroup \catcode`\#=12 \catcode`\&=12 
\input graphs.nw      \endgroup                             \ClearCode

%----------------- mipscoder ---------------------

\input mipscoder.nw      
<<mipscoder>>=
<<*>>
@                           \OutputCode\<ipscoder\>    \ClearCode

%----------------- primes ------------------------

\input primes.nw            
<<primes>>=
<<*>>
@                           \OutputCode\<rimes\>       \ClearCode

%----------------- scanner -----------------------

\input scanner.nw           \OutputCode\<arser\>
                            \OutputCode\<exer\>        \ClearCode

%----------------- test --------------------------

\input test.nw              
<<test>>=         
<<*>>
@                           \OutputCode\<est\>         \ClearCode

%----------------- tree --------------------------

\input tree.nw            
<<tree>>=         
<<*>>
@                           \OutputCode\<ree\>         \ClearCode

%----------------- wc ----------------------------

\input wc.nw                
<<wc>>=         
<<*>>
@                           \OutputCode\<c\>           \ClearCode

\end{document}