#lang scribble/doc
@(require "common.ss" (prefix-in c: "collatz-doc.ss") scribble/struct
          (for-label (only-in scribble/lp chunk)))

@title[#:tag "literate"]{Literate programming}

The techniques used for in-source documentation extend to the creation
of WEB-like literate programming tools. @Figure-ref["Collatz"] shows
an example use of our literate-programming library; the left-hand side
shows a screenshot of DrScheme editing the source code for a short,
literate discussion of the Collatz conjecture, while the right-hand
side shows the rendered output.

In general, literate programs using this library look the same as
other Scribble documents, except that they start with
@code-elem|{#lang scribble/lp}| and use @scheme[chunk] to introduces a
chunk of an implementation. A use of @scheme[chunk] consists of a name
followed by definitions and/or expressions:

@code-block|{
@chunk[<name-of-chunk>
       ... definitions ...
       ... expressions ...]
}|

The definitions and expressions in a chunk can refer to other chunks
by their names.

Unlike a normal Scribble program, running a
@schememodname[scribble/lp] program ignores the prose exposition and
instead evaluates the chunks, also known as @defterm{tangled} program
in literate programming terminology.  Thus, to a client module, a
literate program behaves just like its illiterate variant. The
compiled form of a literate program in does not contain any of the
documentation, nor does it depend on the runtime support for Scribble,
to the literate implementation suffers no overhead due to the prose.

To recover the prose, a @code-block|{@lp-include[_filename]}| form
extracts a literate view of the program in @scheme[_filename], also
known as @defterm{weaving} the program in literate programming
terminology. The right-hand side of @Figure-ref["Collatz"] shows the
woven version of the code in the screenshot.

@bold{Tool support}: 
One difficulty when working with literate programs is that the scope
of variables is obscured, since textually disperate fragments of a
program may end up being woven together into the same scope. When
writing literate programs with Scribble, however, all of the same
tools that operate on normal programs also continue to work for
literate programs. In particular, Check Syntax still draws arrows
properly, showing which variable binders bind which occurrences, as 
shown in @Figure-ref["Collatz"].

Even better, all of the other tool-support that DrScheme provides
continues to work with literate programs, including the interactive
REPL, test case coverage, the module browser, etc.

@;{ Literate programming Scribble is, for now, restricted to languages
that use S-expressions in order to make chunk parsing straightforward,
but given PLT Scheme's flexibility, we expect that we could generalize
the parsing of Literate programs to support other languages easily, if
the need arises. }

To gain some experience with non-trivial literate programming in
Scribble, we have written a 34-page literate program that describes
our implementation of the Chat Noir game that is distirbuted with PLT Scheme. The literate rendering of
the implementation is available at
@show-link{http://docs.plt-scheme.org/games/chat-noir.html}, and the
source is included in he distirbution as @filepath{chat-noir-literate.ss}.

@(figure**
  "Collatz"
  "Literate Programming Example"
  (make-table
   '((row-styles . ([#;(valignment . (top top)) (style . ("Half" "Half"))])))
   (list
    (list (make-flow (list (make-paragraph (list "")) (make-paragraph (list (image #:scale .6 "collatz.png")))))
          (make-flow (list (lp-minipage (make-splice (flow-paragraphs (part-flow c:doc))))))))))