expand Scribble-layers overview
svn: r8241 original commit: 4ba06b7ae0f50c7d0053b4e98de5168240c5fda2
This commit is contained in:
Matthew Flatt
parent
926ff4fbb0
commit
e1dec97903
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
213
collects/scribblings/scribble/layers.scrbl
Normal file
213
collects/scribblings/scribble/layers.scrbl
Normal file
|
|
@ -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.
|
||||
|
|
@ -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"]
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user