From e1dec9790329fc7d26f5c3e39c14b34133634441 Mon Sep 17 00:00:00 2001
From: Matthew Flatt <mflatt@racket-lang.org>
Date: Mon, 7 Jan 2008 03:50:43 +0000
Subject: [PATCH] expand Scribble-layers overview

svn: r8241

original commit: 4ba06b7ae0f50c7d0053b4e98de5168240c5fda2
---
 collects/scribblings/scribble/eval.scrbl     |  12 +-
 collects/scribblings/scribble/how-to.scrbl   |   8 +-
 collects/scribblings/scribble/layers.scrbl   | 213 +++++++++++++++++++
 collects/scribblings/scribble/scribble.scrbl |  77 +------
 collects/scribblings/scribble/style.scrbl    |  18 +-
 5 files changed, 242 insertions(+), 86 deletions(-)
 create mode 100644 collects/scribblings/scribble/layers.scrbl

diff --git a/collects/scribblings/scribble/eval.scrbl b/collects/scribblings/scribble/eval.scrbl
index a0a4af9a..e6b4df83 100644
--- a/collects/scribblings/scribble/eval.scrbl
+++ b/collects/scribblings/scribble/eval.scrbl
@@ -15,7 +15,7 @@ defined procedures and syntax.}
 
 Like @scheme[schemeinput], except that the result for each input
 @scheme[datum] is shown on the next line. The result is determined by
-evaluating the @scheme[quote]d form of the @scheme[datum] using he
+evaluating the @scheme[quote]d form of the @scheme[datum] using the
 evaluator produced by @scheme[eval-expr], if provided.
 
 The @scheme[eval-expr] must produce a sandbox evaluator via
@@ -27,13 +27,9 @@ evaluator is created using @scheme[make-base-eval].
 Uses of @scheme[code:comment] and @schemeidfont{code:blank} are
 stipped from each @scheme[datum] before evaluation.
 
-If a @scheme[datum] has the form @scheme[(#,(scheme code:line)
-_code-datum (#,(scheme code:comment) ...))], then only
-@scheme[_code-datum] is evaluated.
-
-If a datum has the form @scheme[(eval:alts #,(svar show-datum) #,(svar
-eval-datum))], then @svar[show-datum] is typeset, while
-@svar[eval-datum] is evaluated.}
+If a @scheme[datum] has the form @scheme[(eval:alts #,(svar
+show-datum) #,(svar eval-datum))], then @svar[show-datum] is typeset,
+while @svar[eval-datum] is evaluated.}
 
 
 @defform*[[(interaction-eval datum)
diff --git a/collects/scribblings/scribble/how-to.scrbl b/collects/scribblings/scribble/how-to.scrbl
index 3e8122d9..bea7a7f8 100644
--- a/collects/scribblings/scribble/how-to.scrbl
+++ b/collects/scribblings/scribble/how-to.scrbl
@@ -5,6 +5,12 @@
 
 @title{How to Scribble Documentation}
 
+Although the @exec{scribble} command-line utility generates output
+from a Scribble document (run @exec{scribble -h} for more
+information), documentation of PLT Scheme libraries is normally built
+by @exec{setup-plt}. This chapter emphasizes the @exec{setup-plt}
+approach, which more automatically supports links across documents.
+
 @;----------------------------------------
 @section[#:tag "getting-started"]{Getting Started}
 
@@ -64,7 +70,7 @@ EOS
 }
 
 @; ----------------------------------------
-@section{Document Syntax}
+@section[#:tag "how-to:reader"]{Document Syntax}
 
 Whether in ``text'' mode or Scheme mode, @litchar["@"] in a document
 provides an escape to Scheme mode. The syntax of @litchar["@"] is
diff --git a/collects/scribblings/scribble/layers.scrbl b/collects/scribblings/scribble/layers.scrbl
new file mode 100644
index 00000000..b5a0b025
--- /dev/null
+++ b/collects/scribblings/scribble/layers.scrbl
@@ -0,0 +1,213 @@
+#lang scribble/doc
+@(require scribble/manual
+          scribble/bnf
+          "utils.ss")
+
+@title{Scribble Layers}
+
+Scribble is made of independently usable parts.  For example, the
+Scribble reader can be used in any situation that requires lots of
+free-form text. You can also skip Scribble's special reader support,
+and instead use the document-generation structure directly.
+
+@; ----------------------------------------------------------------------
+
+@section{Typical Composition}
+
+A Scribble document normally starts
+
+@schememod[
+scribble/doc
+]
+
+Besides making the file a module, this declaration selects the
+Scribble reader (instead of the usual Scheme reader), and it starts
+the body of the in ``text'' mode. The reader layers mostly leaves text
+alone, but @litchar["@"] forms can escape to S-expression mode.
+
+A module written as
+
+@verbatim[#<<EOS
+  #lang scribble/doc
+
+  @(define to-be "To Be")
+
+  @title{@|to-be| or Not @|to-be|}
+
+  @bold{That} is the question.
+  Whether 'tis nobler...
+EOS
+]
+
+reads as
+
+@schemeblock[
+(module #,(nonterm "name") scribble/doc
+  "\n"
+  (define to-be "To Be") "\n"
+  "\n"
+  (title to-be " or Not " to-be) "\n"
+  "\n"
+  (bold "That") " is the question." "\n"
+  "Whether 'tis nobler..." "\n")
+]
+
+As shown in this example, the read result is a module whose content
+mingles text and definitions. The @schememodname[scribble/doc]
+language lifts definitions, @scheme[require]s, and @scheme[provide]s
+to the beginning of the module, while everything else is collected
+into a document bound to the provided identifier @scheme[doc].  That
+is, the module is transformed to something like this:
+
+@schemeblock[
+(module #,(nonterm "name") scribble/doc
+  (define to-be "To Be")
+  (define doc
+    (decode
+     "\n" "\n" "\n"
+     (title to-be " or Not " to-be) "\n"
+     "\n"
+     (bold "That") " is the question." "\n"
+     "Whether 'tis nobler..." "\n"))
+  (provide doc))
+]
+
+The @scheme[decode] function produces a @scheme[part] structure
+instance that represents the document. To build the @scheme[part]
+instance, it inspects its arguments to find a @scheme[title-decl]
+value created by @scheme[title] to name the part, @scheme[part-start]
+values created @scheme[section] to designate sub-parts, etc.
+
+A @scheme[part] is the input to a rendering back-end, such as the HTML
+renderer. All renderers recognize a fixed structure hierarchy: the
+content of a part is a @defterm{flow}, which is a sequence of
+@defterm{flow elements}, such as paragraphs and tables; a table, in
+turn, consists of a list of list of flows; a paragraph is a list of
+@defterm{elements}, which can be instances of the @scheme[element]
+structure type, plain strings, or certain special symbols.
+
+The value bound to @scheme[doc] in the example above is something like
+
+@schemeblock[
+(make-part ....
+           (list "To Be" " or Not " "To Be")
+           ....
+           (make-flow
+             (list
+              (make-paragraph
+               (list (make-element 'bold (list "That"))
+                     " is the question." "\n"
+                     "Whether " 'rsquo "tis nobler..."))))
+           ....)
+]
+
+Notice that @litchar{'tis} in the input has turned into
+@scheme['rsquo] (a curly apostrophe) followed by @scheme["tis"]. The
+conversion to use @scheme['rsquo] was performed by @scheme[decode] via
+@scheme[decode-flow] to @scheme[decode-paragraph] to
+@scheme[decode-content] to @scheme[decode-string].
+
+The boldface ``That'' as @scheme[(make-element 'bold (list "That"))],
+in contrast, was produced by the @scheme[bold] function.  The
+@scheme[decode] operation is a function, not a syntactic form, and so
+@scheme[bold] has control over its argument before @scheme[decode]
+sees the result. Also, decoding traverses only immediate string
+arguments.
+
+As it turns out, @scheme[bold] also decodes its argument, because the
+@scheme[bold] function is implemented as
+
+@schemeblock[
+(define (bold . strs)
+  (make-element 'bold (decode-content strs)))
+]
+
+The @scheme[verbatim] function, in contrast, does not decode its
+content, and instead typesets its text arguments directly.
+
+A document can construct elements directly using
+@scheme[make-element], but normally functions like @scheme[bold] and
+@scheme[verbatim] to construct them. In particular, the
+@schememodname[scribble/manual] library provides many functions and
+forms to typeset elements and flow elements.
+
+The @scheme[part] structure hierarchy includes built-in element types
+for setting hyperlink targets and references. Again, this machinery is
+normally packaged into higher-level functions and forms, such as
+@scheme[secref], @scheme[defproc], and @scheme[scheme].
+
+@; ----------------------------------------------------------------------
+
+@section{Layer Roadmap}
+
+Working roughly from the bottom up, the Scribble layers are:
+
+@itemize{
+
+ @item{@schememodname[scribble/reader]: A reader that extends the
+       syntax of Scheme with @"@"-forms for conveniently embedding a
+       mixin of text and escapes. See @secref["reader"].}
+
+ @item{@schememodname[scribble/struct]: A set of document datatypes
+       and utilities that define the basic layout and processing of a
+       document. For example, the @scheme[part] datatype is defined in
+       this layer. See @secref["struct"].}
+
+ @item{@schememodname[scribble/base-render] with
+       @schememodname[scribble/html-render],
+       @schememodname[scribble/latex-render], or
+       @schememodname[scribble/text-render]: A base renderer and
+       mixins that generate documents in various formats from
+       instances of the @schememodname[scribble/struct] datatypes. See
+       @secref["renderer"].}
+
+ @item{@schememodname[scribble/decode]: Processes a stream of text,
+       section-start markers, etc. to produce instances of the
+       @schememodname[scribble/struct] datatypes. See
+       @secref["decode"].}
+
+ @item{@schememodname[scribble/doclang]: A language to be used for the
+       initial import of a module; processes the module top level
+       through @schememodname[scribble/decode], and otherwise provides
+       all of @schememodname[scheme/base].  See @secref["doclang"].}
+
+ @item{@schememodname[scribble/doc]: A language that combines
+       @schememodname[scribble/reader] with
+       @schememodname[scribble/doclang]. See @secref["docreader"].}
+
+ @item{@schememodname[scribble/basic]: A library of basic document
+       operators---such as @scheme[title], @scheme[section], and
+       @scheme[secref]---for use with @schememodname[scribble/decode]
+       and a renderer. See @secref["basic"].}
+
+ @item{@schememodname[scribble/scheme]: A library of functions for
+       typesetting Scheme code. See @secref["scheme"]. These functions
+       are not normally used directly, but instead through
+       @schememodname[scribble/manual].}
+
+ @item{@schememodname[scribble/manual]: A library of functions for
+       writing PLT Scheme documentation; re-exports
+       @schememodname[scribble/basic]. Also, the
+       @schememodname[scribble/manual-struct] library provides types
+       for index-entry descriptions created by functions in
+       @schememodname[scribble/manual]. See @secref["manual"].}
+
+ @item{@schememodname[scribble/eval]: A library of functions for
+       evaluating code at document-build time, especially for showing
+       examples. See @secref["eval"].}
+
+ @item{@schememodname[scribble/bnf]: A library of support functions
+       for writing grammars. See @secref["bnf"].}
+
+ @item{@schememodname[scribble/xref]: A library of support functions
+       for using cross-reference information, typically after a
+       document is rendered (e.g., to search). See @secref["xref"].}
+
+}
+
+The @exec{scribble} command-line utility generates output with a
+specified renderer. More specifically, the executable installs a
+renderer, loads the modules specified on the command line, extracts
+the @scheme[doc] export of each module (which must be an instance of
+@scheme[part]), and renders each---potentially with links that span
+documents.
diff --git a/collects/scribblings/scribble/scribble.scrbl b/collects/scribblings/scribble/scribble.scrbl
index 4de6b665..c4f70680 100644
--- a/collects/scribblings/scribble/scribble.scrbl
+++ b/collects/scribblings/scribble/scribble.scrbl
@@ -13,82 +13,7 @@ especially those that document libraries.
 
 @; ------------------------------------------------------------------------
 @include-section["how-to.scrbl"]
-
-@; ------------------------------------------------------------------------
-@section{Scribble Layers}
-
-Scribble is made of independently usable parts.  For example, the
-Scribble reader can be used in any situation that requires lots of
-free-form text. You can also skip Scribble's special reader support,
-and instead use the document-generation structure directly.
-
-The layers are:
-
-@itemize{
-
- @item{@schememodname[scribble/reader]: a reader that extends the
-       syntax of Scheme with @"@"-forms for conveniently embedding a
-       mixin of text and escapes. See @secref["reader"].}
-
- @item{@schememodname[scribble/struct]: a set of document datatypes and utilities
-       that define the basic layout and processing of a document. See
-       @secref["struct"].}
-
- @item{@schememodname[scribble/base-render] with @schememodname[scribble/html-render],
-       @schememodname[scribble/latex-render], or @schememodname[scribble/text-render]: A base
-       renderer and mixins that generate documents in various formats
-       from instances of the @schememodname[scribble/struct] datatypes. See
-       @secref["renderer"].}
-
- @item{@schememodname[scribble/decode]: Processes a stream of text, section-start
-       markers, etc. to produce instances of the @schememodname[scribble/struct]
-       datatypes. See @secref["decode"].}
-
- @item{@schememodname[scribble/doclang]: to be used for the initial import of a
-       module; processes the module top level through
-       @schememodname[scribble/decode], and otherwise provides all of
-       @schememodname[scheme/base].  See @secref["doclang"].}
-
- @item{@schememodname[scribble/doc]: a language that essentially
-       combines @schememodname[scribble/reader] with
-       @schememodname[scribble/doclang]. See @secref["docreader"].}
-
- @item{@schememodname[scribble/basic]: a library of basic document operators---such
-       as @scheme[title], @scheme[section], and @scheme[secref]---for
-       use with @schememodname[scribble/decode] and a renderer. See
-       @secref["basic"].}
-
- @item{@schememodname[scribble/scheme]: a library of support functions for
-       typesetting Scheme code. See @secref["scheme"].}
-
- @item{@schememodname[scribble/manual]: a library of support functions
-       for writing PLT Scheme documentation; re-exports
-       @schememodname[scribble/basic]. Also, the
-       @schememodname[scribble/manual-struct] library provides
-       types for index-entry descriptions created by functions in
-       @schememodname[scribble/manual]. See @secref["manual"].}
-
- @item{@schememodname[scribble/eval]: a library of support functions
-       for evaluating code at document-build time, especially for
-       showing examples. See @secref["eval"].}
-
- @item{@schememodname[scribble/bnf]: a library of support functions for writing
-       grammars. See @secref["bnf"].}
-
- @item{@schememodname[scribble/xref]: a library of support functions
-       for using cross-reference information, typically after a
-       document is rendered (e.g., to search). See @secref["xref"].}
-
-}
-
-The @exec{scribble} command-line utility generates output with a
-specified renderer. More specifically, the executable installs a
-renderer, loads the modules specified on the command line, extracts
-the @scheme[doc] export of each module (which must be an instance of
-@scheme[part]), and renders each. Use @exec{scribble -h} for more
-information.
-
-@; ------------------------------------------------------------------------
+@include-section["layers.scrbl"]
 @include-section["reader.scrbl"]
 @include-section["struct.scrbl"]
 @include-section["renderer.scrbl"]
diff --git a/collects/scribblings/scribble/style.scrbl b/collects/scribblings/scribble/style.scrbl
index ff3cf4f5..01d1c04d 100644
--- a/collects/scribblings/scribble/style.scrbl
+++ b/collects/scribblings/scribble/style.scrbl
@@ -1,10 +1,13 @@
 #lang scribble/doc
 @(require scribble/manual
+          scribble/eval
           "utils.ss"
           (for-label scribble/manual))
 
 @title[#:tag "reference-style"]{Style Guide}
 
+@section{Prose and Terminology}
+
 In the descriptive body of @scheme[defform], @scheme[defproc], etc.,
 do not start with ``This ...'' Instead, start with a sentence whose
 implicit subject is the form or value being described. Thus, the
@@ -17,7 +20,8 @@ values or expressions in a function call.  Refer to libraries and
 languages as such, rather than as ``modules'' (even though the form to
 typeset a library or language name is called @scheme[schememodname]).
 Do not call an identifier (i.e., a syntactic element) a ``variable''
-or a ``symbol.''
+or a ``symbol.'' Do not use the word ``expression'' for a form that is
+a definition or might be a definition; use the word ``form,'' instead.
 
 Avoid cut-and-paste for descriptive text. If two functions are
 similar, consider documenting them together with
@@ -27,6 +31,8 @@ except that ...,'' instead of abstracting the source and instantiating
 it multiple times; often, a prose abstraction is clearer to the reader
 than a hidden abstraction in the document implementation.
 
+@section{Typesetting Code}
+
 Use @schemeidfont{id} or a name that ends @schemeidfont{-id} in
 @scheme[defform] to mean an identifier, not @schemeidfont{identifier},
 @schemeidfont{variable}, @schemeidfont{name}, or
@@ -74,6 +80,16 @@ variable, meta-variable, etc.---use @scheme[schemeidfont] (e.g., as in
 not merely @scheme[schemefont] or @scheme[verbatim], to refer to a
 specific sequence of characters.
 
+When showing example evaluations, use the REPL-snapshot style:
+
+@interaction[
+(+ 1 2)
+]
+
+See also the @scheme[scribble/eval] library.
+
+@section{Typesetting Prose}
+
 Refrain from referring to documentation ``above'' or ``below,'' and
 instead have a hyperlink point to the right place.