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