literate.lyx

   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
  10 %
  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
  52
  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
  77
  78 \begin_body
  79
  80 \begin_layout Part*
  81 Literate programming
  82 \end_layout
  83
  84 \begin_layout Section*
  85 Document license.
  86 \end_layout
  87
  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
  93
  94 \begin_layout Plain Layout
  95 \begin_inset CommandInset href
  96 LatexCommand href
  97 target "http://en.wikipedia.org/wiki/Literate_programming"
  98
  99 \end_inset
 100
 101
 102 \end_layout
 103
 104 \end_inset
 105
 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
 112
 113 \begin_layout Standard
 114 This license is acceptable for Free Cultural Works.
 115 \end_layout
 116
 117 \begin_layout Standard
 118 You are free:
 119 \end_layout
 120
 121 \begin_layout Itemize
 122 to Share — to copy, distribute and transmit the work
 123 \end_layout
 124
 125 \begin_layout Itemize
 126 to Remix — to adapt the work
 127 \end_layout
 128
 129 \begin_layout Standard
 130 Under the following conditions:
 131 \end_layout
 132
 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
 139
 140 \begin_layout List
 141 \labelwidthstring 00.00.0000
 142 Share
 143 \begin_inset space ~
 144 \end_inset
 145
 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
 149
 150 \begin_layout Section*
 151 Literate Programming
 152 \end_layout
 153
 154 \begin_layout Standard
 155
 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
 163
 164 \begin_layout Plain Layout
 165 Knuth, Donald E.
 166  (1984).
 167  "Literate Programming" (PDF).
 168
 169 \shape italic
 170 The Computer Journal
 171 \shape default
 172  (British Computer Society)
 173 \series bold
 174 27
 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"
 183
 184 \end_inset
 185
 186
 187 \end_layout
 188
 189 \end_inset
 190
 191
 192 \end_layout
 193
 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
 201
 202 \begin_layout Plain Layout
 203 \begin_inset Quotes eld
 204 \end_inset
 205
 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
 220
 221  ---
 222 \noun on
 223 Donald E.
 224  Knuth, Literate Programming
 225 \noun default
 226
 227 \begin_inset ERT
 228 status open
 229
 230 \begin_layout Plain Layout
 231
 232
 233 \backslash
 234 footref{fn:w1}
 235 \end_layout
 236
 237 \end_inset
 238
 239
 240 \end_layout
 241
 242 \end_inset
 243
 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
 252
 253 tangled
 254 \begin_inset Quotes erd
 255 \end_inset
 256
 257  code, and another for viewing as formatted documentation, which is said
 258  to be
 259 \begin_inset Quotes eld
 260 \end_inset
 261
 262 woven
 263 \begin_inset Quotes erd
 264 \end_inset
 265
 266  from the literate source.
 267  (If one remembers that the first version of the tool was called
 268 \noun on
 269 WEB
 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
 275
 276 Oh, what a tangled web we weave when first we practise to deceive
 277 \begin_inset Quotes erd
 278 \end_inset
 279
 280  --- Sir Walter Scott, in Canto VI, Stanza 17 of
 281 \begin_inset Quotes eld
 282 \end_inset
 283
 284 Marmion
 285 \begin_inset Quotes erd
 286 \end_inset
 287
 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.
 292
 293 \end_layout
 294
 295 \begin_layout Subsection*
 296 Contents
 297 \end_layout
 298
 299 \begin_layout Standard
 300 \begin_inset CommandInset toc
 301 LatexCommand tableofcontents
 302
 303 \end_inset
 304
 305
 306 \end_layout
 307
 308 \begin_layout Section
 309 Concept
 310 \end_layout
 311
 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.
 327
 328 \end_layout
 329
 330 \begin_layout Standard
 331 A preprocessor is used to substitute arbitrary hierarchies, or rather
 332 \begin_inset Quotes eld
 333 \end_inset
 334
 335 interconnected 'webs' of macros
 336 \begin_inset Quotes erd
 337 \end_inset
 338
 339 ,
 340 \begin_inset Foot
 341 status collapsed
 342
 343 \begin_layout Plain Layout
 344 \begin_inset Quotes eld
 345 \end_inset
 346
 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
 357
 358  ---
 359 \noun on
 360 Donald E.
 361  Knuth, Literate Programming
 362 \noun default
 363
 364 \begin_inset ERT
 365 status open
 366
 367 \begin_layout Plain Layout
 368
 369
 370 \backslash
 371 footref{fn:w1}
 372 \end_layout
 373
 374 \end_inset
 375
 376
 377 \end_layout
 378
 379 \end_inset
 380
 381  to produce the compilable source code with one command (
 382 \begin_inset Quotes eld
 383 \end_inset
 384
 385 tangle
 386 \begin_inset Quotes erd
 387 \end_inset
 388
 389 ), and documentation with another (
 390 \begin_inset Quotes eld
 391 \end_inset
 392
 393 weave
 394 \begin_inset Quotes erd
 395 \end_inset
 396
 397 ).
 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.
 403
 404 \end_layout
 405
 406 \begin_layout Subsection
 407 Advantages of the method
 408 \end_layout
 409
 410 \begin_layout Standard
 411 According to Knuth,
 412 \begin_inset Foot
 413 status collapsed
 414
 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
 433
 434 \end_inset
 435
 436
 437 \begin_inset Foot
 438 status collapsed
 439
 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
 451
 452 \begin_inset ERT
 453 status open
 454
 455 \begin_layout Plain Layout
 456
 457
 458 \backslash
 459 footref{fn:w1}
 460 \end_layout
 461
 462 \end_inset
 463
 464
 465 \end_layout
 466
 467 \end_inset
 468
 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
 477
 478 \begin_layout Plain Layout
 479 \begin_inset Quotes eld
 480 \end_inset
 481
 482 Thus the WEB language allows a person to express programs in a
 483 \shape italic
 484 "stream of consciousness" order
 485 \shape default
 486 .
 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
 504
 505  ---
 506 \noun on
 507 Donald E.
 508  Knuth, Literate Programming
 509 \noun default
 510
 511 \begin_inset ERT
 512 status open
 513
 514 \begin_layout Plain Layout
 515
 516
 517 \backslash
 518 footref{fn:w1}
 519 \end_layout
 520
 521 \end_inset
 522
 523
 524 \end_layout
 525
 526 \end_inset
 527
 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
 539
 540 bird's eye view
 541 \begin_inset Quotes erd
 542 \end_inset
 543
 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.
 548
 549 \end_layout
 550
 551 \begin_layout Subsection
 552 Misconceptions
 553 \end_layout
 554
 555 \begin_layout Standard
 556 Literate programming is very often misunderstood
 557 \begin_inset Foot
 558 status collapsed
 559
 560 \begin_layout Plain Layout
 561 Dominus, Mark-Jason (March 20, 2000).
 562
 563 \begin_inset Quotes eld
 564 \end_inset
 565
 566 POD is not Literate Programming
 567 \begin_inset Quotes erd
 568 \end_inset
 569
 570 .
 571
 572 \shape italic
 573 Perl.com
 574 \shape default
 575 .
 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"
 581
 582 \end_inset
 583
 584
 585 \end_layout
 586
 587 \end_inset
 588
 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
 596
 597 literate programming tools
 598 \begin_inset Quotes erd
 599 \end_inset
 600
 601 .
 602  However, because these tools do not implement the
 603 \begin_inset Quotes eld
 604 \end_inset
 605
 606 web of abstract concepts
 607 \begin_inset Quotes erd
 608 \end_inset
 609
 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
 616
 617 \begin_layout Plain Layout
 618
 619
 620 \backslash
 621 footref{fn:w7}
 622 \end_layout
 623
 624 \end_inset
 625
 626
 627 \begin_inset Foot
 628 status collapsed
 629
 630 \begin_layout Plain Layout
 631 \begin_inset Quotes eld
 632 \end_inset
 633
 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
 646
 647  ---
 648 \noun on
 649 Donald E.
 650  Knuth, Literate Programming
 651 \noun default
 652
 653 \begin_inset ERT
 654 status open
 655
 656 \begin_layout Plain Layout
 657
 658
 659 \backslash
 660 footref{fn:w1}
 661 \end_layout
 662
 663 \end_inset
 664
 665
 666 \end_layout
 667
 668 \end_inset
 669
 670
 671 \end_layout
 672
 673 \begin_layout Section
 674 Example
 675 \end_layout
 676
 677 \begin_layout Standard
 678 A classic example of literate programming is the literate implementation
 679  of the standard Unix
 680 \family typewriter
 681 wc
 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
 693
 694 \begin_layout Plain Layout
 695 Ramsey, Norman (May 13, 2008).
 696
 697 \begin_inset Quotes eld
 698 \end_inset
 699
 700 An Example of noweb
 701 \begin_inset Quotes erd
 702 \end_inset
 703
 704 .
 705  http://www.cs.tufts.edu/
 706 \begin_inset space \space{}
 707 \end_inset
 708
 709 nr/noweb/examples/wc.html.
 710  Retrieved January 4, 2009.
 711 \begin_inset CommandInset label
 712 LatexCommand label
 713 name "fn:w9"
 714
 715 \end_inset
 716
 717
 718 \end_layout
 719
 720 \end_inset
 721
 722  This example provides a good illustration of the basic elements of literate
 723  programming.
 724
 725 \end_layout
 726
 727 \begin_layout Section
 728 Creation of macros
 729 \end_layout
 730
 731 \begin_layout Standard
 732 The following snippet of the
 733 \family typewriter
 734 wc
 735 \family default
 736  literate program
 737 \begin_inset ERT
 738 status open
 739
 740 \begin_layout Plain Layout
 741
 742
 743 \backslash
 744 footref{fn:w9}
 745 \end_layout
 746
 747 \end_inset
 748
 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
 753
 754 operators
 755 \begin_inset Quotes erd
 756 \end_inset
 757
 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
 763
 764
 765 \begin_inset Flex CharStyle:Code
 766 status collapsed
 767
 768 \begin_layout Plain Layout
 769 <<\SpecialChar \ldots{}
 770 >>
 771 \end_layout
 772
 773 \end_inset
 774
 775
 776 \begin_inset Quotes erd
 777 \end_inset
 778
 779 ) that indicate macros, the
 780 \begin_inset Quotes eld
 781 \end_inset
 782
 783
 784 \begin_inset Flex CharStyle:Code
 785 status collapsed
 786
 787 \begin_layout Plain Layout
 788 @
 789 \end_layout
 790
 791 \end_inset
 792
 793
 794 \begin_inset Quotes erd
 795 \end_inset
 796
 797  symbol which indicates the end of the code section in a noweb file.
 798  The
 799 \begin_inset Quotes eld
 800 \end_inset
 801
 802
 803 \begin_inset Flex CharStyle:Code
 804 status collapsed
 805
 806 \begin_layout Plain Layout
 807 <<*>>
 808 \end_layout
 809
 810 \end_inset
 811
 812
 813 \begin_inset Quotes erd
 814 \end_inset
 815
 816  symbol stands for the
 817 \begin_inset Quotes eld
 818 \end_inset
 819
 820 root
 821 \begin_inset Quotes erd
 822 \end_inset
 823
 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
 831
 832
 833 \begin_inset Flex CharStyle:Code
 834 status collapsed
 835
 836 \begin_layout Plain Layout
 837 <<name of the chunk>>=
 838 \end_layout
 839
 840 \end_inset
 841
 842
 843 \begin_inset Quotes erd
 844 \end_inset
 845
 846 , with the equal sign), so one literate program file can contain several
 847  files with machine source code.
 848 \end_layout
 849
 850 \begin_layout Standard
 851 \begin_inset listings
 852 inline false
 853 status open
 854
 855 \begin_layout Plain Layout
 856
 857 The purpose of wc is to count lines, words, and/or characters in a list
 858  of files.
 859  The
 860 \end_layout
 861
 862 \begin_layout Plain Layout
 863
 864 number of lines in a file is ......../more explanations/
 865 \end_layout
 866
 867 \begin_layout Plain Layout
 868
 869 \end_layout
 870
 871 \begin_layout Plain Layout
 872
 873 Here, then, is an overview of the file wc.c that is defined by the noweb
 874  program wc.nw:
 875 \end_layout
 876
 877 \begin_layout Plain Layout
 878
 879         <<*>>=
 880 \end_layout
 881
 882 \begin_layout Plain Layout
 883
 884         <<Header files to include>>
 885 \end_layout
 886
 887 \begin_layout Plain Layout
 888
 889         <<Definitions>>
 890 \end_layout
 891
 892 \begin_layout Plain Layout
 893
 894         <<Global variables>>
 895 \end_layout
 896
 897 \begin_layout Plain Layout
 898
 899         <<Functions>>
 900 \end_layout
 901
 902 \begin_layout Plain Layout
 903
 904         <<The main program>>
 905 \end_layout
 906
 907 \begin_layout Plain Layout
 908
 909 @
 910 \end_layout
 911
 912 \begin_layout Plain Layout
 913
 914 \end_layout
 915
 916 \begin_layout Plain Layout
 917
 918 We must include the standard I/O definitions, since we want to send formatted
 919  output
 920 \end_layout
 921
 922 \begin_layout Plain Layout
 923
 924 to stdout and stderr.
 925 \end_layout
 926
 927 \begin_layout Plain Layout
 928
 929         <<Header files to include>>=
 930 \end_layout
 931
 932 \begin_layout Plain Layout
 933
 934         #include <stdio.h>
 935 \end_layout
 936
 937 \begin_layout Plain Layout
 938
 939         @
 940 \end_layout
 941
 942 \end_inset
 943
 944
 945 \end_layout
 946
 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.
 952
 953 \end_layout
 954
 955 \begin_layout Section
 956 Program as a Web - Macros are not just section names
 957 \end_layout
 958
 959 \begin_layout Standard
 960 Macros are not the same as
 961 \begin_inset Quotes eld
 962 \end_inset
 963
 964 section names
 965 \begin_inset Quotes erd
 966 \end_inset
 967
 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
 974
 975
 976 \begin_inset Flex CharStyle:Code
 977 status collapsed
 978
 979 \begin_layout Plain Layout
 980 if
 981 \end_layout
 982
 983 \end_inset
 984
 985
 986 \begin_inset Quotes erd
 987 \end_inset
 988
 989 ,
 990 \begin_inset Quotes eld
 991 \end_inset
 992
 993
 994 \begin_inset Flex CharStyle:Code
 995 status collapsed
 996
 997 \begin_layout Plain Layout
 998 while
 999 \end_layout
1000
1001 \end_inset
1002
1003
1004 \begin_inset Quotes erd
1005 \end_inset
1006
1007 ,
1008 \begin_inset Quotes eld
1009 \end_inset
1010
1011
1012 \begin_inset Flex CharStyle:Code
1013 status collapsed
1014
1015 \begin_layout Plain Layout
1016 case
1017 \end_layout
1018
1019 \end_inset
1020
1021
1022 \begin_inset Quotes erd
1023 \end_inset
1024
1025 .
1026  This is illustrated by the following snippet of the
1027 \family typewriter
1028 wc
1029 \family default
1030  literate program.
1031 \begin_inset ERT
1032 status open
1033
1034 \begin_layout Plain Layout
1035
1036
1037 \backslash
1038 footref{fn:w9}
1039 \end_layout
1040
1041 \end_inset
1042
1043
1044 \end_layout
1045
1046 \begin_layout Standard
1047 \begin_inset listings
1048 inline false
1049 status open
1050
1051 \begin_layout Plain Layout
1052
1053 \end_layout
1054
1055 \begin_layout Plain Layout
1056
1057 The present chunk, which does the counting that is wc's raison d'etre, was
1058  actually one of
1059 \end_layout
1060
1061 \begin_layout Plain Layout
1062
1063 the simplest to write.
1064  We look at each character and change state if it begins or ends
1065 \end_layout
1066
1067 \begin_layout Plain Layout
1068
1069 a word.
1070 \end_layout
1071
1072 \begin_layout Plain Layout
1073
1074 \end_layout
1075
1076 \begin_layout Plain Layout
1077
1078         <<scan file>>=
1079 \end_layout
1080
1081 \begin_layout Plain Layout
1082
1083         while (1) {
1084 \end_layout
1085
1086 \begin_layout Plain Layout
1087
1088                 <<Fill buffer if it is empty; break at end of file>>
1089 \end_layout
1090
1091 \begin_layout Plain Layout
1092
1093                 c = *ptr++;
1094 \end_layout
1095
1096 \begin_layout Plain Layout
1097
1098                 if (c > ' ' && c < 0177) {
1099 \end_layout
1100
1101 \begin_layout Plain Layout
1102
1103                         /* visible ASCII codes */
1104 \end_layout
1105
1106 \begin_layout Plain Layout
1107
1108                         if (!inword) {
1109 \end_layout
1110
1111 \begin_layout Plain Layout
1112
1113                                 wordcount++;
1114 \end_layout
1115
1116 \begin_layout Plain Layout
1117
1118                                 inword = 1;
1119 \end_layout
1120
1121 \begin_layout Plain Layout
1122
1123                         }
1124 \end_layout
1125
1126 \begin_layout Plain Layout
1127
1128                         continue;
1129 \end_layout
1130
1131 \begin_layout Plain Layout
1132
1133                 }
1134 \end_layout
1135
1136 \begin_layout Plain Layout
1137
1138                 if (c == '
1139 \backslash
1140 n') linecount++;
1141 \end_layout
1142
1143 \begin_layout Plain Layout
1144
1145                 else if (c != ' ' && c != '
1146 \backslash
1147 t') continue;
1148 \end_layout
1149
1150 \begin_layout Plain Layout
1151
1152                 inword = 0;
1153 \end_layout
1154
1155 \begin_layout Plain Layout
1156
1157                 /* c is newline, space, or tab */
1158 \end_layout
1159
1160 \begin_layout Plain Layout
1161
1162         }
1163 \end_layout
1164
1165 \begin_layout Plain Layout
1166
1167         @
1168 \end_layout
1169
1170 \end_inset
1171
1172
1173 \end_layout
1174
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
1180
1181 chunking
1182 \begin_inset Quotes erd
1183 \end_inset
1184
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
1189 web
1190 \shape default
1191  of various parts.
1192 \begin_inset ERT
1193 status open
1194
1195 \begin_layout Plain Layout
1196
1197
1198 \backslash
1199 footref{fn:w1}
1200 \end_layout
1201
1202 \end_inset
1203
1204
1205 \end_layout
1206
1207 \begin_layout Subsection
1208 Order of human logic, not that of the compiler
1209 \end_layout
1210
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
1216
1217
1218 \begin_inset Flex CharStyle:Code
1219 status collapsed
1220
1221 \begin_layout Plain Layout
1222 <<\SpecialChar \ldots{}
1223 >>=
1224 \end_layout
1225
1226 \end_inset
1227
1228
1229 \begin_inset Quotes erd
1230 \end_inset
1231
1232 , can be grown later in any place in the file by simply writing
1233 \begin_inset Quotes eld
1234 \end_inset
1235
1236
1237 \begin_inset Flex CharStyle:Code
1238 status collapsed
1239
1240 \begin_layout Plain Layout
1241 <<name of the chunk>>=
1242 \end_layout
1243
1244 \end_inset
1245
1246
1247 \begin_inset Quotes erd
1248 \end_inset
1249
1250  and adding more content to it, as the following snippet illustrates.
1251 \begin_inset ERT
1252 status open
1253
1254 \begin_layout Plain Layout
1255
1256
1257 \backslash
1258 footref{fn:w1}
1259 \end_layout
1260
1261 \end_inset
1262
1263
1264 \end_layout
1265
1266 \begin_layout Standard
1267 \begin_inset listings
1268 inline false
1269 status open
1270
1271 \begin_layout Plain Layout
1272
1273 The grand totals must be initialized to zero at the beginning of the program.
1274 \end_layout
1275
1276 \begin_layout Plain Layout
1277
1278 If we made these variables local to main, we would have to do this initializatio
1279 n
1280 \end_layout
1281
1282 \begin_layout Plain Layout
1283
1284 explicitly; however, C globals are automatically zeroed.
1285  (Or rather,
1286 \begin_inset Quotes eld
1287 \end_inset
1288
1289 statically
1290 \end_layout
1291
1292 \begin_layout Plain Layout
1293
1294 zeroed.
1295 \begin_inset Quotes erd
1296 \end_inset
1297
1298  (Get it?)
1299 \end_layout
1300
1301 \begin_layout Plain Layout
1302
1303         <<Global variables>>+=
1304 \end_layout
1305
1306 \begin_layout Plain Layout
1307
1308         long totwordcount, totlinecount,
1309 \end_layout
1310
1311 \begin_layout Plain Layout
1312
1313                  totcharcount;
1314 \end_layout
1315
1316 \begin_layout Plain Layout
1317
1318                 /* total number of words, lines, chars */
1319 \end_layout
1320
1321 \begin_layout Plain Layout
1322
1323         @
1324 \end_layout
1325
1326 \end_inset
1327
1328
1329 \end_layout
1330
1331 \begin_layout Subsection
1332 Record of the train of thought creates superior documentation
1333 \end_layout
1334
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
1345
1346 \begin_layout Plain Layout
1347 wc
1348 \end_layout
1349
1350 \end_inset
1351
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
1358
1359 novel
1360 \begin_inset Quotes erd
1361 \end_inset
1362
1363  which explains the code of the computer strategy game Colossal Cave Adventure,
1364  perfectly readable.
1365 \begin_inset Foot
1366 status collapsed
1367
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.
1376
1377 \end_layout
1378
1379 \end_inset
1380
1381
1382 \end_layout
1383
1384 \begin_layout Section
1385 Literate programming tools
1386 \end_layout
1387
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
1401 .
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
1407
1408 \begin_layout Plain Layout
1409 de Marneffe, Pierre Arnoul (December 1973).
1410
1411 \shape italic
1412 Holon Programming - Report PMAR 73-23
1413 \shape default
1414 .
1415  University de Liège, Service d'Informatique.
1416 \end_layout
1417
1418 \end_inset
1419
1420 .
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.
1423
1424 \end_layout
1425
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
1438
1439
1440 \begin_inset Flex CharStyle:Code
1441 status collapsed
1442
1443 \begin_layout Plain Layout
1444 @
1445 \end_layout
1446
1447 \end_inset
1448
1449
1450 \begin_inset Quotes erd
1451 \end_inset
1452
1453  escaping any FunnelWeb command), but has many more flexible options.
1454
1455 \end_layout
1456
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
1470
1471 noweb
1472 \begin_inset Quotes erd
1473 \end_inset
1474
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
1483
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
1491
1492 \end_inset
1493
1494
1495 \end_layout
1496
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
1510
1511 \begin_layout Plain Layout
1512 Hughes, John (January 9, 2002).
1513
1514 \shape italic
1515 Why Functional Programming Matters
1516 \shape default
1517 .
1518  Institutionen för Datavetenskap, Chalmers Tekniska Högskola,.
1519  http://www.cs.chalmers.se/
1520 \begin_inset space ~
1521 \end_inset
1522
1523 rjmh/Papers/whyfp.pdf.
1524  Retrieved January 4, 2009.
1525 \end_layout
1526
1527 \end_inset
1528
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
1533
1534 tangle
1535 \begin_inset Quotes erd
1536 \end_inset
1537
1538  can reorganize in arbitrary ways.
1539
1540 \end_layout
1541
1542 \begin_layout Section
1543 See also
1544 \end_layout
1545
1546 \begin_layout Standard
1547 Sweave - an example of use of the
1548 \begin_inset Quotes eld
1549 \end_inset
1550
1551 noweb
1552 \begin_inset Quotes erd
1553 \end_inset
1554
1555 -like Literate Programming tool inside the R language for creation of dynamic
1556  statistical reports
1557 \end_layout
1558
1559 \begin_layout Section
1560 Further reading
1561 \end_layout
1562
1563 \begin_layout Standard
1564 Knuth, Donald E.
1565  (1992).
1566
1567 \shape italic
1568 Literate Programming
1569 \shape default
1570 .
1571  , California: Stanford University Center for the Study of Language and
1572  Information.
1573  ISBN 978-0937073803.
1574 \begin_inset space ~
1575 \end_inset
1576
1577
1578 \end_layout
1579
1580 \begin_layout Standard
1581 Guari, Eitan M.
1582  (1994).
1583
1584 \shape italic
1585 TeX & LaTeX: Drawing and Literate Programming
1586 \shape default
1587 .
1588  McGraw Hill.
1589  ISBN 0-07-911616-7.
1590 \begin_inset space ~
1591 \end_inset
1592
1593  (includes software).
1594
1595 \end_layout
1596
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
1604
1605 normark/litpro/issues-and-problems.html.
1606 \begin_inset space ~
1607 \end_inset
1608
1609
1610 \end_layout
1611
1612 \begin_layout Section
1613 External links
1614 \end_layout
1615
1616 \begin_layout Standard
1617 comp.programming.literate FAQ at Internet FAQ Archives
1618 \end_layout
1619
1620 \begin_layout Standard
1621 Literate Programming newsgroup
1622 \end_layout
1623
1624 \begin_layout Standard
1625 LiteratePrograms a literate programming wiki.
1626
1627 \end_layout
1628
1629 \begin_layout Standard
1630 Select A literate programming example using noweb
1631 \end_layout
1632
1633 \begin_layout Standard
1634 Softpanorama page on literate programming
1635 \end_layout
1636
1637 \begin_layout Standard
1638 Haskell literate programming
1639 \end_layout
1640
1641 \begin_layout Standard
1642 Specification of literate programming in the Haskell Report the accepted
1643  Haskell standard
1644 \end_layout
1645
1646 \begin_layout Standard
1647 Noweb — A Simple, Extensible Tool for Literate Programming
1648 \end_layout
1649
1650 \begin_layout Standard
1651 Lp4all — A Simple Literate Programming Tool with a wiki-like markup syntax
1652
1653 \end_layout
1654
1655 \end_body
1656 \end_document