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