Editing Literate programming (section)

== Example ==

A classic example of literate programming is the literate implementation of the standard [[Unix]] <code>[[wc (Unix)|wc]]</code> word counting program. Knuth presented a [[CWEB]] version of this example in Chapter 12 of his ''Literate Programming'' book. The same example was later rewritten for the [[noweb]] literate programming tool.<ref name="noweb-wc">{{Cite web |last=Ramsey |first=Norman |date=May 13, 2008 |title=An Example of noweb |url= https://www.cs.tufts.edu/~nr/noweb/examples/wc.html |access-date=January 4, 2009}}</ref> This example provides a good illustration of the basic elements of literate programming.

=== Creation of macros ===
The following snippet of the <code>wc</code> literate program<ref name="noweb-wc" /> shows how arbitrary descriptive phrases in a natural language are used in a literate program to create macros, which act as new "operators" in the literate programming language, and hide chunks of code or other macros. The mark-up notation consists of double angle brackets (<code>&lt;&lt;...&gt;&gt;</code>) that indicate macros. The <code>@</code> symbol which, in a noweb file, indicates the beginning of a documentation chunk. The <code>&lt;&lt;*&gt;&gt;</code> symbol stands for the "root", topmost node the literate programming tool will start expanding the web of macros from. Actually, writing out the expanded source code can be done from any section or subsection (i.e. a piece of code designated as <code>&lt;&lt;name of the chunk&gt;&gt;=</code>, with the equal sign), so one literate program file can contain several files with machine source code.
<syntaxhighlight lang="c">
The purpose of wc is to count lines, words, and/or characters in a list of files. The
number of lines in a file is ......../more explanations/

Here, then, is an overview of the file wc.c that is defined by the noweb program wc.nw:
    <<*>>=
    <<Header files to include>>
    <<Definitions>>
    <<Global variables>>
    <<Functions>>
    <<The main program>>
    @

We must include the standard I/O definitions, since we want to send formatted output
to stdout and stderr.
    <<Header files to include>>=
    #include <stdio.h>
    @
</syntaxhighlight>
The unraveling of the chunks can be done in any place in the literate program text file, not necessarily in the order they are sequenced in the enclosing chunk, but as is demanded by the logic reflected in the explanatory text that envelops the whole program.

=== Program as a web ===
Macros are not the same as "section names" in standard documentation. Literate programming macros hide the real code behind themselves, and be used inside any low-level machine language operators, often inside logical operators such as <code>if</code>, <code>while</code> or <code>case</code>. This can be seen in the following <code>wc</code> literate program.<ref name="noweb-wc" />

<syntaxhighlight lang="c">
The present chunk, which does the counting, was actually one of
the simplest to write. We look at each character and change state if it begins or ends
a word.

    <<Scan file>>=
    while (1) {
      <<Fill buffer if it is empty; break at end of file>>
      c = *ptr++;
      if (c > ' ' && c < 0177) {
        /* visible ASCII codes */
        if (!in_word) {
          word_count++;
          in_word = 1;
        }
        continue;
      }
      if (c == '\n') line_count++;
      else if (c != ' ' && c != '\t') continue;
      in_word = 0;
        /* c is newline, space, or tab */
    }
    @
</syntaxhighlight>

The macros stand for any chunk of code or other macros, and are more general than top-down or bottom-up "chunking", or than subsectioning. Donald Knuth said that when he realized this, he began to think of a program as a ''web'' of various parts.<ref name="TCJ_LP" />

=== Order of human logic, not that of the compiler ===
In a noweb literate program besides the free order of their exposition, the chunks behind macros, once introduced with <code>&lt;&lt;...&gt;&gt;=</code>, can be grown later in any place in the file by simply writing <code>&lt;&lt;name of the chunk&gt;&gt;=</code> and adding more content to it, as the following snippet illustrates (<code>+</code> is added by the document formatter for readability, and is not in the code).<ref name="noweb-wc" />

{{pre|1=
The grand totals must be initialized to zero at the beginning of the program.
If we made these variables local to main, we would have to do this  initialization
explicitly; however, C globals are automatically zeroed. (Or rather,``statically
zeroed.'&NoBreak;' (Get it?)

    &lt;&lt;Global variables&gt;&gt;+=
    {{codett|2=c|long tot_word_count, tot_line_count,}}
         tot_char_count;
      {{codett|2=c|/* total number of words, lines, chars */}}
    @
}}

=== Record of the train of thought ===
The documentation for a literate program is produced as part of writing the program. Instead of comments provided as side notes to source code a literate program contains the explanation of concepts on each level, with lower level concepts deferred to their appropriate place, which allows for  better communication of thought. The snippets of the literate <code>wc</code> above show how an explanation of the program and its source code are interwoven. Such exposition of ideas creates the flow of thought that is like a literary work. Knuth wrote a "novel" which explains the code of the [[interactive fiction]] game [[Colossal Cave Adventure]].<ref>The game, also known as ''ADVENT'', was originally written by Crowther in about 700 lines of FORTRAN code; Knuth recast it into the WEB idiom. It is available at [http://www.literateprogramming.com/cweb_download.html literateprogramming.com] or on [https://cs.stanford.edu/~knuth/programs.html Knuth's website] {{webarchive|url= https://web.archive.org/web/20080820091137/http://sunburn.stanford.edu/~knuth/programs.html |date=August 20, 2008}}.</ref>

=== Remarkable examples ===
* [[Axiom (computer algebra system)|Axiom]], which is evolved from scratchpad, a computer algebra system developed by IBM. It is now being developed by Tim Daly, one of the developers of scratchpad, Axiom is totally written as a literate program.