From db70d62ca717d7602ec0fd0efe2dba9e15e9fe38 Mon Sep 17 00:00:00 2001 From: Matthew Flatt Date: Thu, 26 Feb 2009 22:49:07 +0000 Subject: [PATCH] adjust scribble/lp docs svn: r13859 --- collects/scribblings/scribble/config.scrbl | 2 +- collects/scribblings/scribble/lp-ex-doc.scrbl | 4 ++ collects/scribblings/scribble/lp-ex.ss | 1 + collects/scribblings/scribble/lp.css | 4 ++ collects/scribblings/scribble/lp.scrbl | 49 +++++++++++++------ collects/scribblings/scribble/lp.tex | 3 ++ 6 files changed, 46 insertions(+), 17 deletions(-) create mode 100644 collects/scribblings/scribble/lp-ex-doc.scrbl create mode 100644 collects/scribblings/scribble/lp.css create mode 100644 collects/scribblings/scribble/lp.tex diff --git a/collects/scribblings/scribble/config.scrbl b/collects/scribblings/scribble/config.scrbl index 0d03105771..2f145316d5 100644 --- a/collects/scribblings/scribble/config.scrbl +++ b/collects/scribblings/scribble/config.scrbl @@ -58,7 +58,7 @@ To avoid collisions with future additions to Scribble, start your style name with an uppercase letter that is not @litchar{S}. An uppercase letter helps to avoid collisions with macros defined by Latex packages, and future styles needed by @scheme[scribble/manual] -will start with @litchar{s}. +will start with @litchar{S}. For example, a Scribble document diff --git a/collects/scribblings/scribble/lp-ex-doc.scrbl b/collects/scribblings/scribble/lp-ex-doc.scrbl new file mode 100644 index 0000000000..2d3bd6ae6f --- /dev/null +++ b/collects/scribblings/scribble/lp-ex-doc.scrbl @@ -0,0 +1,4 @@ +#lang scribble/doc +@(require scribble/lp-include) + +@lp-include["lp-ex.ss"] diff --git a/collects/scribblings/scribble/lp-ex.ss b/collects/scribblings/scribble/lp-ex.ss index 3fc74b37b2..34017c90e5 100644 --- a/collects/scribblings/scribble/lp-ex.ss +++ b/collects/scribblings/scribble/lp-ex.ss @@ -1,4 +1,5 @@ #lang scribble/lp + Literate programs have chunks of code, like this one: @chunk[ diff --git a/collects/scribblings/scribble/lp.css b/collects/scribblings/scribble/lp.css new file mode 100644 index 0000000000..638efcd2a1 --- /dev/null +++ b/collects/scribblings/scribble/lp.css @@ -0,0 +1,4 @@ +.LPBoxed { + padding: 1ex; + border: 1px solid #000000; +} diff --git a/collects/scribblings/scribble/lp.scrbl b/collects/scribblings/scribble/lp.scrbl index 83f1d6da19..5c457ec385 100644 --- a/collects/scribblings/scribble/lp.scrbl +++ b/collects/scribblings/scribble/lp.scrbl @@ -1,26 +1,34 @@ #lang scribble/doc -@(require scribble/manual scheme/runtime-path scribble/lp-include) +@(require scribble/manual + scribble/struct + scheme/runtime-path + (prefix-in lp-ex: "lp-ex-doc.scrbl") + "utils.ss" + (for-label scribble/lp-include + (only-in scribble/private/lp chunk))) -@title[#:tag "lp"]{Literate Programming} +@title[#:tag "lp" #:style `((css "lp.css") (tex "lp.tex")) ]{Literate Programming} Programs written using @schememodname[scribble/lp] are simultaneously -two things: a program, and a document describing the program. +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 +ways, either by running the program directly or by including it with +@scheme[lp-include]. 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 +program, and the rest of the module is discarded. When using +@scheme[lp-include], 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 + #:indent 2 (apply string-append (let loop () @@ -36,25 +44,34 @@ 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"] +@(make-blockquote + "LPBoxed" + (flow-paragraphs (part-flow lp-ex:doc))) -@section{@schememodname[scribble/lp] language} +@section{@schememodname[scribble/lp] Language} -@defmodulelang[scribble/lp]{This is a Scribble's core support for Literate Programming.} +@declare-exporting[scribble/private/lp] -@defform[(chunk expressions ...)]{ - Introduces a chunk, binding @scheme[] for use in other chunks. +@defmodulelang*/no-declare[(scribble/lp)]{The +@schememodname[scribble/lp] language provides core support for +literate programming.} - If @scheme[] is @tt{<*>}, then this chunk is used as the main - chunk in the file. If @tt{<*>} is never used, then the first chunk +@defform[(chunk id form ...)]{ + + Introduces a chunk, binding @scheme[id] for use in other + chunks. Normally, @scheme[id] starts with @litchar{<} and ends with + @litchar{>}. + + If @scheme[id] is @schemeidfont{<*>}, then this chunk is used as the main + chunk in the file. If @schemeidfont{<*>} is never used, then the first chunk in the file is treated as the main chunk. } -@section{@schememodname[scribble/lp-include] module} +@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/lp.tex b/collects/scribblings/scribble/lp.tex new file mode 100644 index 0000000000..fcbaecac57 --- /dev/null +++ b/collects/scribblings/scribble/lp.tex @@ -0,0 +1,3 @@ + +\usepackage{framed} +\newenvironment{LPBoxed}{\begin{framed}}{\end{framed}}