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