WIP
[newfangle.git] / literate.lyx
blob113b3dfb6163877a9b7031a037d847be45014e5b
1 #LyX 1.6.4 created this file. For more info see http://www.lyx.org/
2 \lyxformat 345
3 \begin_document
4 \begin_header
5 \textclass article
6 \begin_preamble
7 % This file was converted from HTML to LaTeX with
8 % Tomasz Wegrzanowski's <maniek@beer.com> gnuhtml2latex program
9 % Version : 0.1
11 % This text is taken from Wikipedia, the free encyclopedia, presented here
12 %  under the Creative Commons Attribution-Share Alike 3.0 Unported license.
13
14 % This license is acceptable for Free Cultural Works.
15
16 % You are free:
17
18 % * to Share - to copy, distribute and transmit the work
19
20 % * to Remix - to adapt the work
21
22 % Under the following conditions:
23
24 % Attribution - You must attribute the work in the manner specified by the 
25 % author or licensor (but not in any way that suggests that they endorse 
26 % you or your use of the work).
27
28 % Share Alike If you alter, transform, or build upon this work, you may 
29 % distribute the resulting work only under the same, similar or a 
30 % compatible license.
31
32 \usepackage{footmisc}
33 \lstset{numbers=left, stepnumber=1, numbersep=5pt, breaklines=false,
34 basicstyle=\footnotesize\ttfamily,
35 numberstyle=\tiny,language=C,columns=fullflexible,
36 numberfirstline=true}
37 \end_preamble
38 \use_default_options false
39 \begin_modules
40 logicalmkup
41 \end_modules
42 \language english
43 \inputencoding auto
44 \font_roman default
45 \font_sans default
46 \font_typewriter default
47 \font_default_family default
48 \font_sc false
49 \font_osf false
50 \font_sf_scale 100
51 \font_tt_scale 100
53 \graphics default
54 \paperfontsize default
55 \spacing single
56 \use_hyperref false
57 \papersize default
58 \use_geometry false
59 \use_amsmath 1
60 \use_esint 1
61 \cite_engine basic
62 \use_bibtopic false
63 \paperorientation portrait
64 \secnumdepth 3
65 \tocdepth 3
66 \paragraph_separation skip
67 \defskip medskip
68 \quotes_language english
69 \papercolumns 1
70 \papersides 1
71 \paperpagestyle default
72 \tracking_changes false
73 \output_changes false
74 \author "" 
75 \author "" 
76 \end_header
78 \begin_body
80 \begin_layout Part*
81 Literate programming
82 \end_layout
84 \begin_layout Section*
85 Document license.
86 \end_layout
88 \begin_layout Standard
89 (C) Copyright various Wikipedia Contributors.
90  This text is taken from Wikipedia, the free encyclopedia
91 \begin_inset Foot
92 status open
94 \begin_layout Plain Layout
95 \begin_inset CommandInset href
96 LatexCommand href
97 target "http://en.wikipedia.org/wiki/Literate_programming"
99 \end_inset
102 \end_layout
104 \end_inset
106 , presented here under the 
107 \noun on
108 Creative Commons
109 \noun default
110  Attribution-Share Alike 3.0 Unported license.
111 \end_layout
113 \begin_layout Standard
114 This license is acceptable for Free Cultural Works.
115 \end_layout
117 \begin_layout Standard
118 You are free:
119 \end_layout
121 \begin_layout Itemize
122 to Share — to copy, distribute and transmit the work
123 \end_layout
125 \begin_layout Itemize
126 to Remix — to adapt the work
127 \end_layout
129 \begin_layout Standard
130 Under the following conditions:
131 \end_layout
133 \begin_layout List
134 \labelwidthstring 00.00.0000
135 Attribution You must attribute the work in the manner specified by the author
136  or licensor (but not in any way that suggests that they endorse you or
137  your use of the work).
138 \end_layout
140 \begin_layout List
141 \labelwidthstring 00.00.0000
142 Share
143 \begin_inset space ~
144 \end_inset
146 Alike If you alter, transform, or build upon this work, you may distribute
147  the resulting work only under the same, similar or a compatible license.
148 \end_layout
150 \begin_layout Section*
151 Literate Programming
152 \end_layout
154 \begin_layout Standard
156 \series bold
157 Literate programming
158 \series default
159  is an approach to programming introduced by Donald Knuth as an alternative
160  to the structured programming paradigm of the 1970s.
161 \begin_inset Foot
162 status collapsed
164 \begin_layout Plain Layout
165 Knuth, Donald E.
166  (1984).
167  "Literate Programming" (PDF).
169 \shape italic
170 The Computer Journal
171 \shape default
172  (British Computer Society) 
173 \series bold
175 \series default
176  (2): 97-111.
177  doi:10.1093/comjnl/27.2.97.
178  http://www.literateprogramming.com/knuthweb.pdf.
179  Retrieved January 4, 2009.
180 \begin_inset CommandInset label
181 LatexCommand label
182 name "fn:w1"
184 \end_inset
187 \end_layout
189 \end_inset
192 \end_layout
194 \begin_layout Standard
195 The literate programming paradigm, as conceived by Knuth, represents a move
196  away from writing programs in the manner and order imposed by the computer,
197  and instead enables programmers to develop programs in the order demanded
198  by the logic and flow of their thoughts.
199 \begin_inset Foot
200 status collapsed
202 \begin_layout Plain Layout
203 \begin_inset Quotes eld
204 \end_inset
206 I had the feeling that top-down and bottom-up were opposing methodologies:
207  one more suitable for program exposition and the other more suitable for
208  program creation.
209  But after gaining experience with WEB, I have come to realize that there
210  is no need to choose once and for all between top-down and bottom-up, because
211  a program is best thought of as a web instead of a tree.
212  A hierarchical structure is present, but the most important thing about
213  a program is its structural relationships.
214  A complex piece of software consists of simple parts and simple relations
215  between those parts; the programmer's task is to state those parts and
216  those relationships, in whatever order is best for human comprehension
217  not in some rigidly determined order like top-down or bottom-up.
218 \begin_inset Quotes erd
219 \end_inset
221  --- 
222 \noun on
223 Donald E.
224  Knuth, Literate Programming
225 \noun default
227 \begin_inset ERT
228 status open
230 \begin_layout Plain Layout
233 \backslash
234 footref{fn:w1}
235 \end_layout
237 \end_inset
240 \end_layout
242 \end_inset
244  Literate programs are written as an uninterrupted exposition of logic in
245  an ordinary human language, much like the text of an essay, in which macros
246  which hide abstractions and traditional source code are included.
247  Literate programming tools are used to obtain two representations from
248  a literate source file: one suitable for further compilation or execution
249  by a computer, the 
250 \begin_inset Quotes eld
251 \end_inset
253 tangled
254 \begin_inset Quotes erd
255 \end_inset
257  code, and another for viewing as formatted documentation, which is said
258  to be 
259 \begin_inset Quotes eld
260 \end_inset
262 woven
263 \begin_inset Quotes erd
264 \end_inset
266  from the literate source.
267  (If one remembers that the first version of the tool was called 
268 \noun on
270 \noun default
271 , the amusing literary reference hidden by Knuth in these names becomes
272  obvious: 
273 \begin_inset Quotes eld
274 \end_inset
276 Oh, what a tangled web we weave when first we practise to deceive
277 \begin_inset Quotes erd
278 \end_inset
280  --- Sir Walter Scott, in Canto VI, Stanza 17 of 
281 \begin_inset Quotes eld
282 \end_inset
284 Marmion
285 \begin_inset Quotes erd
286 \end_inset
288  (1808) an epic poem about the Battle of Flodden Field in 1513.).
289  While the first generation of literate programming tools were computer
290  language-specific, the later ones are language-agnostic and exist above
291  the programming languages.
293 \end_layout
295 \begin_layout Subsection*
296 Contents
297 \end_layout
299 \begin_layout Standard
300 \begin_inset CommandInset toc
301 LatexCommand tableofcontents
303 \end_inset
306 \end_layout
308 \begin_layout Section
309 Concept
310 \end_layout
312 \begin_layout Standard
313 A literate program is an explanation of the program logic in a natural language,
314  such as English, interspersed with snippets of macros and traditional source
315  code.
316  Macros in a literate source file are simply title-like or explanatory phrases
317  in a human language that describe human abstractions created while solving
318  the programming problem, and hiding chunks of code or lower-level macros.
319  These macros are similar to the algorithms in pseudocode typically used
320  in teaching computer science.
321  These arbitrary explanatory phrases become precise new operators, created
322  on the fly by the programmer, forming a 
323 \shape italic
324 meta-language
325 \shape default
326  on top of the underlying programming language.
328 \end_layout
330 \begin_layout Standard
331 A preprocessor is used to substitute arbitrary hierarchies, or rather 
332 \begin_inset Quotes eld
333 \end_inset
335 interconnected 'webs' of macros
336 \begin_inset Quotes erd
337 \end_inset
340 \begin_inset Foot
341 status collapsed
343 \begin_layout Plain Layout
344 \begin_inset Quotes eld
345 \end_inset
347 WEB's macros are allowed to have at most one parameter.
348  Again, I did this in the interests of simplicity, because I noticed that
349  most applications of multiple parameters could in fact be reduced to the
350  one-parameter case.
351  For example, suppose that you want to define something like...
352  In other words, the name of one macro can usefully be a parameter to another
353  macro.
354  This particular trick makes it possible to...
355 \begin_inset Quotes erd
356 \end_inset
358  --- 
359 \noun on
360 Donald E.
361  Knuth, Literate Programming
362 \noun default
364 \begin_inset ERT
365 status open
367 \begin_layout Plain Layout
370 \backslash
371 footref{fn:w1}
372 \end_layout
374 \end_inset
377 \end_layout
379 \end_inset
381  to produce the compilable source code with one command (
382 \begin_inset Quotes eld
383 \end_inset
385 tangle
386 \begin_inset Quotes erd
387 \end_inset
389 ), and documentation with another (
390 \begin_inset Quotes eld
391 \end_inset
393 weave
394 \begin_inset Quotes erd
395 \end_inset
398  The preprocessor also provides an ability to write out the content of the
399  macros and to add to already created macros in any place in the text of
400  the literate program source file, thereby disposing of the need to keep
401  in mind the restrictions imposed by traditional programming languages or
402  to interrupt the flow of thought.
404 \end_layout
406 \begin_layout Subsection
407 Advantages of the method
408 \end_layout
410 \begin_layout Standard
411 According to Knuth,
412 \begin_inset Foot
413 status collapsed
415 \begin_layout Plain Layout
416 Knuth, Donald E.; Andrew Binstock (April 25, 2008).
417  "Interview with Donald Knuth".
418  http://www.informit.com/articles/article.aspx?p=1193856.
419  Retrieved January 4, 2009.
420  "Yet to me, literate programming is certainly the most important thing
421  that came out of the TeX project.
422  Not only has it enabled me to write and maintain programs faster and more
423  reliably than ever before, and been one of my greatest sources of joy since
424  the 1980s-it has actually been indispensable at times.
425  Some of my major programs, such as the MMIX meta-simulator, could not have
426  been written with any other methodology that I've ever heard of.
427  The complexity was simply too daunting for my limited brain to handle;
428  without literate programming, the whole enterprise would have flopped miserably.
429  ...
430  Literate programming is what you need to rise above the ordinary level
431  of achievement."
432 \end_layout
434 \end_inset
437 \begin_inset Foot
438 status collapsed
440 \begin_layout Plain Layout
441 "Another surprising thing that I learned while using WEB was that traditional
442  programming languages had been causing me to write inferior programs, although
443  I hadn't realized what I was doing.
444  My original idea was that WEB would be merely a tool for documentation,
445  but I actually found that my WEB programs were better than the programs
446  I had been writing in other languages." --- 
447 \noun on
448 Donald E.
449  Knuth, Literate Programming
450 \noun default
452 \begin_inset ERT
453 status open
455 \begin_layout Plain Layout
458 \backslash
459 footref{fn:w1}
460 \end_layout
462 \end_inset
465 \end_layout
467 \end_inset
469  literate programming provides for higher-quality programs, since it forces
470  programmers to explicitly state the thoughts behind the program, making
471  poorly thought-out design decisions more obvious.
472  Knuth also claims that literate programming provides a first-rate documentation
473  system, which is not an add-on, but is grown naturally in the process of
474  exposition of one's thoughts during a program creation.
475 \begin_inset Foot
476 status collapsed
478 \begin_layout Plain Layout
479 \begin_inset Quotes eld
480 \end_inset
482 Thus the WEB language allows a person to express programs in a 
483 \shape italic
484 "stream of consciousness" order
485 \shape default
487  TANGLE is able to scramble everything up into the arrangement that a PASCAL
488  compiler demands.
489  This feature of WEB is perhaps its greatest asset; it makes a WEB-written
490  program much more readable than the same program written purely in PASCAL,
491  even if the latter program is well commented.
492  And the fact that there's no need to be hung up on the question of top-down
493  versus bottom-up, since a programmer can now 
494 \shape italic
495 view a large program as a web, to be explored in a 
496 \series bold
497 psychologically correct order
498 \series default
499  is perhaps the greatest lesson
500 \shape default
501  I have learned from my recent experiences.
502 \begin_inset Quotes erd
503 \end_inset
505  --- 
506 \noun on
507 Donald E.
508  Knuth, Literate Programming
509 \noun default
511 \begin_inset ERT
512 status open
514 \begin_layout Plain Layout
517 \backslash
518 footref{fn:w1}
519 \end_layout
521 \end_inset
524 \end_layout
526 \end_inset
528  The resulting documentation allows authors to restart their own thought
529  processes at any later time, and allows other programmers to more easily
530  understand the construction of the program.
531  This differs from traditional documentation, in which a programmer is presented
532  with source code that follows a compiler-imposed order, and must decipher
533  the thought process behind the program from the code and its associated
534  comments.
535  The meta-language capabilities of literate programming are also claimed
536  to facilitate thinking in general, giving a higher 
537 \begin_inset Quotes eld
538 \end_inset
540 bird's eye view
541 \begin_inset Quotes erd
542 \end_inset
544  of the code and increasing the number of concepts the mind can successfully
545  retain and process.
546  Applicability of the concept to programming on a large scale, that of commercia
547 l-grade programs is proven by an edition of TeX code as a literate program.
549 \end_layout
551 \begin_layout Subsection
552 Misconceptions
553 \end_layout
555 \begin_layout Standard
556 Literate programming is very often misunderstood
557 \begin_inset Foot
558 status collapsed
560 \begin_layout Plain Layout
561 Dominus, Mark-Jason (March 20, 2000).
563 \begin_inset Quotes eld
564 \end_inset
566 POD is not Literate Programming
567 \begin_inset Quotes erd
568 \end_inset
572 \shape italic
573 Perl.com
574 \shape default
576  http://www.perl.com/pub/a/tchrist/litprog.html.
577  Retrieved January 3, 2009.
578 \begin_inset CommandInset label
579 LatexCommand label
580 name "fn:w7"
582 \end_inset
585 \end_layout
587 \end_inset
589  to refer only to formatted documentation produced from a common file with
590  both source code and comments, or to voluminous commentaries included with
591  code.
592  This misconception has led to claims that comment-extraction tools, such
593  as the Perl Plain Old Documentation system, are 
594 \begin_inset Quotes eld
595 \end_inset
597 literate programming tools
598 \begin_inset Quotes erd
599 \end_inset
602  However, because these tools do not implement the 
603 \begin_inset Quotes eld
604 \end_inset
606 web of abstract concepts
607 \begin_inset Quotes erd
608 \end_inset
610  hiding behind the system of natural-language macros, or provide an ability
611  to change the order of the source code from a machine-imposed sequence
612  to one convenient to the human mind, they cannot properly be called literate
613  programming tools in the sense intended by Knuth.
614 \begin_inset ERT
615 status open
617 \begin_layout Plain Layout
620 \backslash
621 footref{fn:w7}
622 \end_layout
624 \end_inset
627 \begin_inset Foot
628 status collapsed
630 \begin_layout Plain Layout
631 \begin_inset Quotes eld
632 \end_inset
634 I chose the name WEB partly because it was one of the few three-letter words
635  of English that hadn't already been applied to computers.
636  But as time went on, I've become extremely pleased with the name, because
637  I think that a complex piece of software is, indeed, best regarded as a
638  web that has been delicately pieced together from simple materials.
639  We understand a complicated system by understanding its simple parts, and
640  by understanding the simple relations between those parts and their immediate
641  neighbors.
642  If we express a program as a web of ideas, we can emphasize its structural
643  properties in a natural and satisfying way.
644 \begin_inset Quotes erd
645 \end_inset
647  --- 
648 \noun on
649 Donald E.
650  Knuth, Literate Programming
651 \noun default
653 \begin_inset ERT
654 status open
656 \begin_layout Plain Layout
659 \backslash
660 footref{fn:w1}
661 \end_layout
663 \end_inset
666 \end_layout
668 \end_inset
671 \end_layout
673 \begin_layout Section
674 Example
675 \end_layout
677 \begin_layout Standard
678 A classic example of literate programming is the literate implementation
679  of the standard Unix 
680 \family typewriter
682 \family default
683  word counting program.
684  Knuth presented a CWEB version of this example in Chapter 12 of his 
685 \shape italic
686 Literate Programming
687 \shape default
688  book.
689  The same example was later rewritten for the noweb literate programming
690  tool.
691 \begin_inset Foot
692 status open
694 \begin_layout Plain Layout
695 Ramsey, Norman (May 13, 2008).
697 \begin_inset Quotes eld
698 \end_inset
700 An Example of noweb
701 \begin_inset Quotes erd
702 \end_inset
705  http://www.cs.tufts.edu/
706 \begin_inset space \space{}
707 \end_inset
709 nr/noweb/examples/wc.html.
710  Retrieved January 4, 2009.
711 \begin_inset CommandInset label
712 LatexCommand label
713 name "fn:w9"
715 \end_inset
718 \end_layout
720 \end_inset
722  This example provides a good illustration of the basic elements of literate
723  programming.
725 \end_layout
727 \begin_layout Section
728 Creation of macros 
729 \end_layout
731 \begin_layout Standard
732 The following snippet of the 
733 \family typewriter
735 \family default
736  literate program
737 \begin_inset ERT
738 status open
740 \begin_layout Plain Layout
743 \backslash
744 footref{fn:w9}
745 \end_layout
747 \end_inset
749  shows how arbitrary descriptive phrases in a natural language are used
750  in a literate program to create macros, which act as new 
751 \begin_inset Quotes eld
752 \end_inset
754 operators
755 \begin_inset Quotes erd
756 \end_inset
758  in the literate programming language, and hide chunks of code or other
759  macros.
760  The mark-up notation consists of double angle brackets (
761 \begin_inset Quotes eld
762 \end_inset
765 \begin_inset Flex CharStyle:Code
766 status collapsed
768 \begin_layout Plain Layout
769 <<\SpecialChar \ldots{}
771 \end_layout
773 \end_inset
776 \begin_inset Quotes erd
777 \end_inset
779 ) that indicate macros, the 
780 \begin_inset Quotes eld
781 \end_inset
784 \begin_inset Flex CharStyle:Code
785 status collapsed
787 \begin_layout Plain Layout
789 \end_layout
791 \end_inset
794 \begin_inset Quotes erd
795 \end_inset
797  symbol which indicates the end of the code section in a noweb file.
798  The 
799 \begin_inset Quotes eld
800 \end_inset
803 \begin_inset Flex CharStyle:Code
804 status collapsed
806 \begin_layout Plain Layout
807 <<*>>
808 \end_layout
810 \end_inset
813 \begin_inset Quotes erd
814 \end_inset
816  symbol stands for the 
817 \begin_inset Quotes eld
818 \end_inset
820 root
821 \begin_inset Quotes erd
822 \end_inset
824 , topmost node the literate programming tool will start expanding the web
825  of macros from.
826  Actually, writing out the expanded source code can be done from any section
827  or subsection (i.e.
828  a piece of code designated as 
829 \begin_inset Quotes erd
830 \end_inset
833 \begin_inset Flex CharStyle:Code
834 status collapsed
836 \begin_layout Plain Layout
837 <<name of the chunk>>=
838 \end_layout
840 \end_inset
843 \begin_inset Quotes erd
844 \end_inset
846 , with the equal sign), so one literate program file can contain several
847  files with machine source code.
848 \end_layout
850 \begin_layout Standard
851 \begin_inset listings
852 inline false
853 status open
855 \begin_layout Plain Layout
857 The purpose of wc is to count lines, words, and/or characters in a list
858  of files.
859  The
860 \end_layout
862 \begin_layout Plain Layout
864 number of lines in a file is ......../more explanations/ 
865 \end_layout
867 \begin_layout Plain Layout
869 \end_layout
871 \begin_layout Plain Layout
873 Here, then, is an overview of the file wc.c that is defined by the noweb
874  program wc.nw:
875 \end_layout
877 \begin_layout Plain Layout
879         <<*>>=
880 \end_layout
882 \begin_layout Plain Layout
884         <<Header files to include>>
885 \end_layout
887 \begin_layout Plain Layout
889         <<Definitions>>
890 \end_layout
892 \begin_layout Plain Layout
894         <<Global variables>>
895 \end_layout
897 \begin_layout Plain Layout
899         <<Functions>>
900 \end_layout
902 \begin_layout Plain Layout
904         <<The main program>>
905 \end_layout
907 \begin_layout Plain Layout
910 \end_layout
912 \begin_layout Plain Layout
914 \end_layout
916 \begin_layout Plain Layout
918 We must include the standard I/O definitions, since we want to send formatted
919  output
920 \end_layout
922 \begin_layout Plain Layout
924 to stdout and stderr.
925 \end_layout
927 \begin_layout Plain Layout
929         <<Header files to include>>=
930 \end_layout
932 \begin_layout Plain Layout
934         #include <stdio.h>
935 \end_layout
937 \begin_layout Plain Layout
939         @
940 \end_layout
942 \end_inset
945 \end_layout
947 \begin_layout Standard
948 Note also that the unraveling of the chunks can be done in any place in
949  the literate program text file, not necessarily in the order they are sequenced
950  in the enclosing chunk, but as is demanded by the logic reflected in the
951  explanatory text that envelops the whole program.
953 \end_layout
955 \begin_layout Section
956 Program as a Web - Macros are not just section names
957 \end_layout
959 \begin_layout Standard
960 Macros are not the same as 
961 \begin_inset Quotes eld
962 \end_inset
964 section names
965 \begin_inset Quotes erd
966 \end_inset
968  in standard documentation.
969  Literate programming macros can hide any chunk of code behind themselves,
970  and be used inside any low-level machine language operators, often inside
971  logical operators such as 
972 \begin_inset Quotes eld
973 \end_inset
976 \begin_inset Flex CharStyle:Code
977 status collapsed
979 \begin_layout Plain Layout
981 \end_layout
983 \end_inset
986 \begin_inset Quotes erd
987 \end_inset
990 \begin_inset Quotes eld
991 \end_inset
994 \begin_inset Flex CharStyle:Code
995 status collapsed
997 \begin_layout Plain Layout
998 while
999 \end_layout
1001 \end_inset
1004 \begin_inset Quotes erd
1005 \end_inset
1008 \begin_inset Quotes eld
1009 \end_inset
1012 \begin_inset Flex CharStyle:Code
1013 status collapsed
1015 \begin_layout Plain Layout
1016 case
1017 \end_layout
1019 \end_inset
1022 \begin_inset Quotes erd
1023 \end_inset
1026  This is illustrated by the following snippet of the 
1027 \family typewriter
1029 \family default
1030  literate program.
1031 \begin_inset ERT
1032 status open
1034 \begin_layout Plain Layout
1037 \backslash
1038 footref{fn:w9}
1039 \end_layout
1041 \end_inset
1044 \end_layout
1046 \begin_layout Standard
1047 \begin_inset listings
1048 inline false
1049 status open
1051 \begin_layout Plain Layout
1053 \end_layout
1055 \begin_layout Plain Layout
1057 The present chunk, which does the counting that is wc's raison d'etre, was
1058  actually one of
1059 \end_layout
1061 \begin_layout Plain Layout
1063 the simplest to write.
1064  We look at each character and change state if it begins or ends
1065 \end_layout
1067 \begin_layout Plain Layout
1069 a word.
1070 \end_layout
1072 \begin_layout Plain Layout
1074 \end_layout
1076 \begin_layout Plain Layout
1078         <<scan file>>=
1079 \end_layout
1081 \begin_layout Plain Layout
1083         while (1) {
1084 \end_layout
1086 \begin_layout Plain Layout
1088                 <<Fill buffer if it is empty; break at end of file>>
1089 \end_layout
1091 \begin_layout Plain Layout
1093                 c = *ptr++;
1094 \end_layout
1096 \begin_layout Plain Layout
1098                 if (c > ' ' && c < 0177) {
1099 \end_layout
1101 \begin_layout Plain Layout
1103                         /* visible ASCII codes */
1104 \end_layout
1106 \begin_layout Plain Layout
1108                         if (!inword) {
1109 \end_layout
1111 \begin_layout Plain Layout
1113                                 wordcount++;
1114 \end_layout
1116 \begin_layout Plain Layout
1118                                 inword = 1;
1119 \end_layout
1121 \begin_layout Plain Layout
1123                         }
1124 \end_layout
1126 \begin_layout Plain Layout
1128                         continue;
1129 \end_layout
1131 \begin_layout Plain Layout
1133                 }
1134 \end_layout
1136 \begin_layout Plain Layout
1138                 if (c == '
1139 \backslash
1140 n') linecount++; 
1141 \end_layout
1143 \begin_layout Plain Layout
1145                 else if (c != ' ' && c != '
1146 \backslash
1147 t') continue;
1148 \end_layout
1150 \begin_layout Plain Layout
1152                 inword = 0;
1153 \end_layout
1155 \begin_layout Plain Layout
1157                 /* c is newline, space, or tab */ 
1158 \end_layout
1160 \begin_layout Plain Layout
1162         }
1163 \end_layout
1165 \begin_layout Plain Layout
1167         @
1168 \end_layout
1170 \end_inset
1173 \end_layout
1175 \begin_layout Standard
1176 In fact, macros can stand for any arbitrary chunk of code or other macros,
1177  and are thus more general than top-down or bottom-up 
1178 \begin_inset Quotes eld
1179 \end_inset
1181 chunking
1182 \begin_inset Quotes erd
1183 \end_inset
1185 , or than subsectioning.
1186  Knuth says that when he realized this, he began to think of a program as
1187  a 
1188 \shape italic
1190 \shape default
1191  of various parts.
1192 \begin_inset ERT
1193 status open
1195 \begin_layout Plain Layout
1198 \backslash
1199 footref{fn:w1}
1200 \end_layout
1202 \end_inset
1205 \end_layout
1207 \begin_layout Subsection
1208 Order of human logic, not that of the compiler
1209 \end_layout
1211 \begin_layout Standard
1212 In a noweb literate program besides the free order of their exposition,
1213  the chunks behind macros, once introduced with 
1214 \begin_inset Quotes eld
1215 \end_inset
1218 \begin_inset Flex CharStyle:Code
1219 status collapsed
1221 \begin_layout Plain Layout
1222 <<\SpecialChar \ldots{}
1224 \end_layout
1226 \end_inset
1229 \begin_inset Quotes erd
1230 \end_inset
1232 , can be grown later in any place in the file by simply writing 
1233 \begin_inset Quotes eld
1234 \end_inset
1237 \begin_inset Flex CharStyle:Code
1238 status collapsed
1240 \begin_layout Plain Layout
1241 <<name of the chunk>>=
1242 \end_layout
1244 \end_inset
1247 \begin_inset Quotes erd
1248 \end_inset
1250  and adding more content to it, as the following snippet illustrates.
1251 \begin_inset ERT
1252 status open
1254 \begin_layout Plain Layout
1257 \backslash
1258 footref{fn:w1}
1259 \end_layout
1261 \end_inset
1264 \end_layout
1266 \begin_layout Standard
1267 \begin_inset listings
1268 inline false
1269 status open
1271 \begin_layout Plain Layout
1273 The grand totals must be initialized to zero at the beginning of the program.
1274 \end_layout
1276 \begin_layout Plain Layout
1278 If we made these variables local to main, we would have to do this initializatio
1280 \end_layout
1282 \begin_layout Plain Layout
1284 explicitly; however, C globals are automatically zeroed.
1285  (Or rather,
1286 \begin_inset Quotes eld
1287 \end_inset
1289 statically
1290 \end_layout
1292 \begin_layout Plain Layout
1294 zeroed.
1295 \begin_inset Quotes erd
1296 \end_inset
1298  (Get it?)
1299 \end_layout
1301 \begin_layout Plain Layout
1303         <<Global variables>>+=
1304 \end_layout
1306 \begin_layout Plain Layout
1308         long totwordcount, totlinecount, 
1309 \end_layout
1311 \begin_layout Plain Layout
1313                  totcharcount; 
1314 \end_layout
1316 \begin_layout Plain Layout
1318                 /* total number of words, lines, chars */
1319 \end_layout
1321 \begin_layout Plain Layout
1323         @
1324 \end_layout
1326 \end_inset
1329 \end_layout
1331 \begin_layout Subsection
1332 Record of the train of thought creates superior documentation
1333 \end_layout
1335 \begin_layout Standard
1336 The documentation for a literate program is produced as part of writing
1337  the program.
1338  Instead of comments provided as side notes to source code a literate program
1339  contains the explanation of concepts on each level, with lower level concepts
1340  deferred to their appropriate place, which allows for better communication
1341  of thought.
1342  The snippets of the literate 
1343 \begin_inset Flex CharStyle:Code
1344 status collapsed
1346 \begin_layout Plain Layout
1348 \end_layout
1350 \end_inset
1352  above show how an explanation of the program and its source code are interwoven.
1353  Such exposition of ideas creates the flow of thought that is like a literary
1354  work.
1355  Knuth famously wrote a 
1356 \begin_inset Quotes eld
1357 \end_inset
1359 novel
1360 \begin_inset Quotes erd
1361 \end_inset
1363  which explains the code of the computer strategy game Colossal Cave Adventure,
1364  perfectly readable.
1365 \begin_inset Foot
1366 status collapsed
1368 \begin_layout Plain Layout
1369 The game, also known as 
1370 \shape italic
1371 ADVENT
1372 \shape default
1373 , was originally written by Crowther in about 700 lines of FORTRAN code;
1374  Knuth recast it into the WEB idiom.
1375  It is available at literateprogramming.com or on Knuth's website.
1377 \end_layout
1379 \end_inset
1382 \end_layout
1384 \begin_layout Section
1385 Literate programming tools
1386 \end_layout
1388 \begin_layout Standard
1389 The first published literate programming environment was WEB, introduced
1390  by Donald Knuth in 1981 for his TeX typesetting system; it uses Pascal
1391  as its underlying programming language and TeX for typesetting of the documenta
1392 tion.
1393  The complete commented TeX source code was published in Knuth's 
1394 \shape italic
1395 TeX: The program
1396 \shape default
1397 , volume B of his 5-volume 
1398 \shape italic
1399 Computers and Typesetting
1400 \shape default
1402  Knuth had privately used a literate programming system called DOC as early
1403  as 1979.
1404  He was inspired by the ideas of Pierre-Arnoul de Marneffe
1405 \begin_inset Foot
1406 status collapsed
1408 \begin_layout Plain Layout
1409 de Marneffe, Pierre Arnoul (December 1973).
1411 \shape italic
1412 Holon Programming - Report PMAR 73-23
1413 \shape default
1415  University de Liège, Service d'Informatique.
1416 \end_layout
1418 \end_inset
1421  The free CWEB, written by Knuth and Silvio Levy, is WEB adapted for C and
1422  C++, runs on most operating systems and can produce TeX and PDF documentation.
1424 \end_layout
1426 \begin_layout Standard
1427 Other implementations of the literate programming concept are noweb and
1428  FunnelWeb, both of which are independent of the programming language of
1429  the source code.
1430  Noweb is well-known for its simplicity: just 2 text markup conventions
1431  and 2 tool invocations are needed to use it, and it allows for text formatting
1432  in HTML rather than going through the TeX system.
1433  FunnelWeb is another program without dependency on TeX which can produce
1434  HTML documentation output.
1435  It has more complicated markup (with 
1436 \begin_inset Quotes eld
1437 \end_inset
1440 \begin_inset Flex CharStyle:Code
1441 status collapsed
1443 \begin_layout Plain Layout
1445 \end_layout
1447 \end_inset
1450 \begin_inset Quotes erd
1451 \end_inset
1453  escaping any FunnelWeb command), but has many more flexible options.
1455 \end_layout
1457 \begin_layout Standard
1458 The Leo text editor is an 
1459 \shape italic
1460 outlining
1461 \shape default
1462  editor which supports optional noweb and CWEB markup.
1463  The author of Leo actually mixes two different approaches: first, Leo is
1464  an outlining editor, which helps with management of large texts, second,
1465  Leo incorporates some of the ideas of literate programming, which in its
1466  pure form (i.e.
1467  the way it is used by Knuth Web tool and/or tools like 
1468 \begin_inset Quotes eld
1469 \end_inset
1471 noweb
1472 \begin_inset Quotes erd
1473 \end_inset
1475 ) is possible only with some degree of inventiveness and the use of the
1476  editor in a way not exactly envisioned by its author (in modified @root
1477  nodes).
1478  However this and other extensions (@file nodes) make outline programming
1479  and text management successful and easy and in some ways similar to literate
1480  programming.
1481 \begin_inset Foot
1482 status collapsed
1484 \begin_layout Plain Layout
1485 Ream, Edward K.
1486  (September 2, 2008).
1487  "Leo's Home Page".
1488  http://webpages.charter.net/edreamleo/front.html.
1489  Retrieved January 4, 2009.
1490 \end_layout
1492 \end_inset
1495 \end_layout
1497 \begin_layout Standard
1498 The Haskell programming language has native support for semi-literate programmin
1499 g, inspired by CWEB but with a simpler implementation.
1500  When aiming for TeX output, one writes a plain LaTeX file where source
1501  code is marked by a given surrounding environment; LaTeX can be set up
1502  to handle that environment, while the Haskell compiler looks for the right
1503  markers to identify Haskell statements to compile, removing the TeX documentati
1504 on as if they were comments.
1505  However, as described above, this is not literate programming in the sense
1506  intended by Knuth.
1507  Haskell's functional, modular nature
1508 \begin_inset Foot
1509 status collapsed
1511 \begin_layout Plain Layout
1512 Hughes, John (January 9, 2002).
1514 \shape italic
1515 Why Functional Programming Matters
1516 \shape default
1518  Institutionen för Datavetenskap, Chalmers Tekniska Högskola,.
1519  http://www.cs.chalmers.se/
1520 \begin_inset space ~
1521 \end_inset
1523 rjmh/Papers/whyfp.pdf.
1524  Retrieved January 4, 2009.
1525 \end_layout
1527 \end_inset
1529  makes literate programming directly in the language somewhat easier, but
1530  it is not nearly as powerful as one of the a WEB tools where 
1531 \begin_inset Quotes eld
1532 \end_inset
1534 tangle
1535 \begin_inset Quotes erd
1536 \end_inset
1538  can reorganize in arbitrary ways.
1540 \end_layout
1542 \begin_layout Section
1543 See also
1544 \end_layout
1546 \begin_layout Standard
1547 Sweave - an example of use of the 
1548 \begin_inset Quotes eld
1549 \end_inset
1551 noweb
1552 \begin_inset Quotes erd
1553 \end_inset
1555 -like Literate Programming tool inside the R language for creation of dynamic
1556  statistical reports 
1557 \end_layout
1559 \begin_layout Section
1560 Further reading
1561 \end_layout
1563 \begin_layout Standard
1564 Knuth, Donald E.
1565  (1992).
1567 \shape italic
1568 Literate Programming
1569 \shape default
1571  , California: Stanford University Center for the Study of Language and
1572  Information.
1573  ISBN 978-0937073803.
1574 \begin_inset space ~
1575 \end_inset
1578 \end_layout
1580 \begin_layout Standard
1581 Guari, Eitan M.
1582  (1994).
1584 \shape italic
1585 TeX & LaTeX: Drawing and Literate Programming
1586 \shape default
1588  McGraw Hill.
1589  ISBN 0-07-911616-7.
1590 \begin_inset space ~
1591 \end_inset
1593  (includes software).
1595 \end_layout
1597 \begin_layout Standard
1598 Nørmark, Kurt (August 13, 1998).
1599  "Literate Programming - Issues and Problems".
1600  University of Aalborg.
1601  http://www.cs.aau.dk/
1602 \begin_inset space ~
1603 \end_inset
1605 normark/litpro/issues-and-problems.html.
1606 \begin_inset space ~
1607 \end_inset
1610 \end_layout
1612 \begin_layout Section
1613 External links
1614 \end_layout
1616 \begin_layout Standard
1617 comp.programming.literate FAQ at Internet FAQ Archives 
1618 \end_layout
1620 \begin_layout Standard
1621 Literate Programming newsgroup 
1622 \end_layout
1624 \begin_layout Standard
1625 LiteratePrograms a literate programming wiki.
1627 \end_layout
1629 \begin_layout Standard
1630 Select A literate programming example using noweb 
1631 \end_layout
1633 \begin_layout Standard
1634 Softpanorama page on literate programming 
1635 \end_layout
1637 \begin_layout Standard
1638 Haskell literate programming 
1639 \end_layout
1641 \begin_layout Standard
1642 Specification of literate programming in the Haskell Report the accepted
1643  Haskell standard 
1644 \end_layout
1646 \begin_layout Standard
1647 Noweb — A Simple, Extensible Tool for Literate Programming 
1648 \end_layout
1650 \begin_layout Standard
1651 Lp4all — A Simple Literate Programming Tool with a wiki-like markup syntax
1653 \end_layout
1655 \end_body
1656 \end_document