commit e1dec9790329fc7d26f5c3e39c14b34133634441
parent 926ff4fbb0af8f5bd689184a1c94952782e77e9f
Author: Matthew Flatt <mflatt@racket-lang.org>
Date: Mon, 7 Jan 2008 03:50:43 +0000
expand Scribble-layers overview
svn: r8241
original commit: 4ba06b7ae0f50c7d0053b4e98de5168240c5fda2
Diffstat:
5 files changed, 242 insertions(+), 86 deletions(-)
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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.
