commit 7bef14c014a25e351ec443ac7ffb2dfb602d54bf
parent d62f6ee503968197380188d29c2ba44a883ce776
Author: Robby Findler <robby@racket-lang.org>
Date: Thu, 26 Feb 2009 21:08:05 +0000
first cut docs for literate programming
svn: r13856
original commit: 9f465fb91764558495d7019af21eac846eb11b01
Diffstat:
4 files changed, 78 insertions(+), 0 deletions(-)
diff --git a/collects/launcher/sh b/collects/launcher/sh
diff --git a/collects/scribblings/scribble/lp-ex.ss b/collects/scribblings/scribble/lp-ex.ss
@@ -0,0 +1,16 @@
+#lang scribble/lp
+Literate programs have chunks of code, like this one:
+
+@chunk[<f>
+ (define (f x)
+ <fs-body>)]
+
+and this one:
+
+@chunk[<fs-body>
+ (* x x)]
+
+that, when assembled, produce a complete program, in this case:
+
+@schemeblock[(define (f x)
+ (* x x))]
diff --git a/collects/scribblings/scribble/lp.scrbl b/collects/scribblings/scribble/lp.scrbl
@@ -0,0 +1,60 @@
+#lang scribble/doc
+@(require scribble/manual scheme/runtime-path scribble/lp-include)
+
+@title[#:tag "lp"]{Literate Programming}
+
+Programs written using @schememodname[scribble/lp] are simultaneously
+two things: a program, and a document describing the program.
+
+Programs in @schememodname[scribble/lp] are viewed in two different
+ways, either by running the program directly, or by including it with
+@scheme[include-lp]. When running the program, all of the
+@scheme[chunk] expressions are collected and stitched together into a
+program and the rest of the module is discarded. When using
+@scheme[include-lp], the entire contents of the module are preserved
+and are treated like an ordinary Scribble document, where
+@scheme[chunk]s are typeset in a manner similar to @scheme[codeblock].
+
+@(define-runtime-path lp-ex "lp-ex.ss")
+
+For example, consider this program:
+@(call-with-input-file lp-ex
+ (lambda (port)
+ (verbatim
+ (apply
+ string-append
+ (let loop ()
+ (let ([line (read-line port 'any)])
+ (cond
+ [(eof-object? line) '()]
+ [(equal? line "") (cons " \n" (loop))]
+ [else
+ (list* line "\n" (loop))])))))))
+
+When this file is @scheme[require]d in the normal manner, it defines a
+function @scheme[f] that squares its argument, and the documentation
+is ignored. When it is included with @scheme[lp-include], it looks
+like this:
+
+@lp-include["lp-ex.ss"]
+
+@section{@schememodname[scribble/lp] language}
+
+@defmodulelang[scribble/lp]{This is a Scribble's core support for Literate Programming.}
+
+@defform[(chunk <id> expressions ...)]{
+ Introduces a chunk, binding @scheme[<id>] for use in other chunks.
+
+ If @scheme[<id>] is @tt{<*>}, then this chunk is used as the main
+ chunk in the file. If @tt{<*>} is never used, then the first chunk
+ in the file is treated as the main chunk.
+}
+
+@section{@schememodname[scribble/lp-include] module}
+
+@defmodule[scribble/lp-include]{}
+
+@defform[(lp-include filename)]{
+Includes the source of @scheme[filename] as the typeset version of the literate
+program.
+}
+\ No newline at end of file
diff --git a/collects/scribblings/scribble/scribble.scrbl b/collects/scribblings/scribble/scribble.scrbl
@@ -37,6 +37,7 @@ starting with the @filepath{scribble.scrbl} file.
@include-section["eval.scrbl"]
@include-section["srcdoc.scrbl"]
@include-section["bnf.scrbl"]
+@include-section["lp.scrbl"]
@include-section["xref.scrbl"]
@include-section["preprocessor.scrbl"]
@include-section["config.scrbl"]
