suzanne.soy/scribble-enhanced
1
0
Fork 0
Code Issues 1 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

catch up scribble reference

Browse Source 
svn: r7051

original commit: 1b6483bc36b16f86b306ab6334cc1b44d1ee08d0
This commit is contained in:
Matthew Flatt 2007-08-08 02:45:25 +00:00
parent f7803f005e
commit 648facb9e4
9 changed files with 436 additions and 85 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
collects/scribble/basic.ss
View File

@ -122,7 +122,7 @@
(provide section-index index index* as-index index-section)
(define (section-index . elems)
(make-section-index-decl (map element->string elems) elems))
(make-part-index-decl (map element->string elems) elems))
(define (gen-target)
(format "index:~s:~s" (current-inexact-milliseconds) (gensym)))

10
collects/scribble/decode.ss
View File

@ -20,8 +20,8 @@
[tag (or/c false/c string?)]
[title list?])]
[splice ([run list?])]
[section-index-decl ([plain-seq (listof string?)]
[entry-seq list?])])
[part-index-decl ([plain-seq (listof string?)]
[entry-seq list?])])
(define (decode-string s)
(let loop ([l '((#rx"---" mdash)
@ -68,8 +68,8 @@
#f
null
`(part ,tag)
(section-index-decl-plain-seq k)
(section-index-decl-entry-seq k)))
(part-index-decl-plain-seq k)
(part-index-decl-entry-seq k)))
keys tags)])
(if title
(cons (make-index-element
@ -152,7 +152,7 @@
[(splice? (car l))
(loop (append (splice-run (car l)) (cdr l)) next? keys accum title tag style)]
[(null? (cdr l)) (loop null #f keys (cons (car l) accum) title tag style)]
[(section-index-decl? (car l))
[(part-index-decl? (car l))
(loop (cdr l) next? (cons (car l) keys) accum title tag style)]
[(and (pair? (cdr l))
(splice? (cadr l)))

11
collects/scribble/manual.ss
View File

@ -1088,17 +1088,6 @@
;; ----------------------------------------
(provide where-is-one-of
is-one-of)
(define (where-is-one-of id)
(make-element #f (list "where " id " is one of")))
(define (is-one-of id)
(make-element #f (list id " is one of")))
;; ----------------------------------------
(provide math)
(define (math . s)
(let ([c (decode-content s)])

64
collects/scribblings/scribble/basic.scrbl
View File

@ -42,17 +42,31 @@ Although the procedures are mostly design to be used from @elem["@"]
mode, they are easier to document in Scheme mode (partly because we
have Scribble's @file{scheme.ss} and @file{manual.ss}).
@; ------------------------------------------------------------------------
@section{Document Structure}
@defproc[(title [#:tag tag (or/c false/c string?) #f]
[#:style style any/c #f]
[pre-content any/c] ...+)
title-decl?]{ Generates a @scheme[title-decl] to
be picked up by @scheme[decode] or @scheme[decode-part]. The
@scheme[pre-content]s list is parsed with @scheme[decode-content] for
the title content. If @scheme[tag] is @scheme[#f], a tag string is
generated automatically from the content. The tag string is combined
with the symbol @scheme['part] to form the full tag.}
title-decl?]{
Generates a @scheme[title-decl] to be picked up by @scheme[decode] or
@scheme[decode-part]. The @scheme[pre-content]s list is parsed with
@scheme[decode-content] for the title content. If @scheme[tag] is
@scheme[#f], a tag string is generated automatically from the
content. The tag string is combined with the symbol @scheme['part] to
form the full tag.
A style of @scheme['toc] causes sub-sections to be generated as
separate pages in multi-page HTML output. A style of @scheme['index]
indicates an index section whose body is rendered in two columns for
Latex output.
The section title is automatically indexed. For the index key, a
leading ``A'', ``An'', or ``The'' (followed by whitespace) is
removed.}
@def-section-like[section part-start?]{ Like @scheme[title], but
generates a @scheme[part-start] of depth @scheme[0] to be by
@ -87,6 +101,8 @@ have Scribble's @file{scheme.ss} and @file{manual.ss}).
visible to the enclosing context). Since this form expands to
@scheme[require], it must be used in a module or top-level context.}
@; ------------------------------------------------------------------------
@section{Text Styles}
@def-elem-proc[elem]{ Parses the @scheme[pre-content] list using
@ -114,6 +130,8 @@ and produces an element with style @scheme[style-name].
}
@; ------------------------------------------------------------------------
@section{Indexing}
@defproc[(index [words (or/c string? (listof string?))]
@ -143,15 +161,37 @@ the list of contents render in the index (in parallel to
index-element?]{
Like @scheme[index], but the word to index is determined by applying
@scheme[content->string] on the parsed @scheme[pre-content] list.
@scheme[content->string] on the parsed @scheme[pre-content] list.}
}
@defproc[(section-index [word string?] ...)]{
Creates a @scheme[part-index-decl] to be associated with the enclosing
section by @scheme[decode]. The @scheme[word]s serve as both the keys
and as the rendered forms of the keys.}
@defproc[(index-section [tag string?])]{
Produces a section that shows the index the enclosing document. The
@scheme[tag] is required to be unique for each index among a set of
documents that share ``collected'' information.}
@; ------------------------------------------------------------------------
@section{Tables of Contents}
@defproc[(table-of-contents) delayed-flow-element?]{
Returns a flow element that expands to a table of contents for the
enclosing section. For LaTeX output, however, the table of contents
currently spans the entire enclosing document.
}
Returns a delayed flow element that expands to a table of contents for
the enclosing section. For LaTeX output, however, the table of
contents currently spans the entire enclosing document.}
@defproc[(local-table-of-contents) delayed-flow-element?]{
Returns a delayed flow element that may expand to a table of contents
for the enclosing section, depending on the output type. For
multi-page HTML output, the flow element is a table of contents; for
Latex output, the flow element is empty.}

17
collects/scribblings/scribble/decode.scrbl
View File

@ -34,10 +34,12 @@ special text conversions:
Decodes a document, producing a part. In @scheme[lst], instances of
@scheme[splice] are inlined into the list. An instance of
@scheme[title-decl] supplies the title for the part. Instances of
@scheme[part-start] at level 0 trigger sub-part parsing. Instances of
@scheme[section] trigger are used as-is as subsections, and instances
of @scheme[paragraph] and other flow-element datatypes are used as-is
in the enclosing flow.
@scheme[index-section-decl] (that preceed any sub-part) add index
entries that point to the section. Instances of @scheme[part-start] at
level 0 trigger sub-part parsing. Instances of @scheme[section]
trigger are used as-is as subsections, and instances of
@scheme[paragraph] and other flow-element datatypes are used as-is in
the enclosing flow.
}
@ -103,6 +105,13 @@ See @scheme[decode] and @scheme[decode-part].
}
@defstruct[part-index-decl ([plain-seq (listof string?)]
[content-seq list?])]{
See @scheme[decode]. The two fields are as for @scheme[index-element].
}
@defstruct[splice ([run list?])]{
See @scheme[decode], @scheme[decode-part], and @scheme[decode-flow].

245
collects/scribblings/scribble/manual.scrbl
View File

@ -9,7 +9,7 @@ The @file{manual.ss} module provides all of @file{basic.ss}, and
more...
@; ------------------------------------------------------------------------
@section{Typesetting Code}
@section[#:tag "scribble:manual:code"]{Typesetting Code}
@defform[(schemeblock datum ...)]{
@ -109,6 +109,13 @@ module whose language is @scheme[lang].}
a single line and wrapped with its enclosing paragraph, independent of
the formatting of @scheme[datum].}
@defform[(indexed-scheme datum ...)]{
A combination of @scheme[scheme] and @scheme[as-index], with the
special case that if a single @scheme[datum] is provided and it is a
@scheme[quote] form, then the quote is removed from the key (so that
it's sorted using its unquoted form).}
@defform[(schemeresult datum ...)]{Like @scheme[scheme], but typeset
as a REPL value (i.e., a single color with no hyperlinks).}
@ -145,9 +152,16 @@ for typesetting things like @scheme{#module}, which are not
@defproc[(schemekeywordfont [pre-content any/c] ...) element?]{Like
@scheme[schemefont], but colored as a syntactic form name.}
@defproc[(schemeparenfont [pre-content any/c] ...) element?]{Like
@scheme[schemefont], but colored like parentheses.}
@defproc[(schememetafont [pre-content any/c] ...) element?]{Like
@scheme[schemefont], but colored as meta-syntax, such as backquote or
unquote.}
@defproc[(procedure [pre-content any/c] ...) element?]{Typesets the given
content as a procedure name in a REPL result (e.g., in typewriter font
with a @schemefont{#<procedure:} prefix and @schemefont{>} suffix.).}
with a @litchar{#<procedure:} prefix and @litchar{>} suffix.).}
@defform[(var datum)]{Typesets @scheme[var] as an identifier that is
an argument or sub-form in a procedure being
@ -167,9 +181,10 @@ in a form definition.}
pre-flow ...)]{
Produces a sequence of flow elements (encaptured in a @scheme[splice])
to document a procedure named @scheme[id]. The @scheme[id] is
registered so that @scheme[scheme]-typeset uses of the identifier
(with the same lexical binding) are hyperlinked to this documentation.
to document a procedure named @scheme[id]. The @scheme[id] is indexed,
and it also registered so that @scheme[scheme]-typeset uses of the
identifier (with the same lexical binding) are hyperlinked to this
documentation.
Each @scheme[arg-spec] must have one of the following forms:
@ -222,9 +237,9 @@ Like @scheme[defproc], but for multiple cases with the same
Produces a a sequence of flow elements (encaptured in a
@scheme[splice]) to document a syntatic form named by @scheme[id]. The
@scheme[id] is registered so that @scheme[scheme]-typeset uses of the
identifier (with the same lexical binding) are hyperlinked to this
documentation.
@scheme[id] is indexed, and it is also registered so that
@scheme[scheme]-typeset uses of the identifier (with the same lexical
binding) are hyperlinked to this documentation.
The @scheme[pre-flow]s list is parsed as a flow that documents the
procedure. In this description, a reference to any identifier in
@ -240,24 +255,33 @@ layout, like @scheme[schemeblock], and unlike @scheme[defproc].}
Like @scheme[defform], but for multiple forms using the same
@scheme[id].}
@defform/subs[(defform/subs maybe-literals (id . datum)
([nonterm-id clause-datum ...+] ...)
pre-flow ...)
([maybe-literals code:blank
(code:line #:literals (literal-id ...))])]{
@defform[(defform/subs maybe-literals (id . datum)
([nonterm-id clause-datum ...+] ...)
pre-flow ...)]{
Like @scheme[defform], but including an auxiliary grammar of
non-terminals shown with the @scheme[id] form. Each
@scheme[nonterm-id] is specified as being any of the corresponding
@scheme[clause-datum]s, where the formatting of each
@scheme[clause-datum] is preserved.}
@defform/subs[(specform maybe-literals (id . datum) pre-flow ...)
([maybe-literals code:blank
(code:line #:literals (literal-id ...))])]{
Like @scheme[defform], with without registering a definition, and with
indenting on the left for both the specification and the
@scheme[pre-flow]s.}
@defform[(defform/none datum pre-flow ...)]{
Like @scheme[defform], but without registering a definition.}
@defform[(defidform id pre-flow ...)]{
Like @scheme[defform], but with a plain @scheme[id] as the form.}
@defform[(specform maybe-literals (id . datum) pre-flow ...)]{
Like @scheme[defform], with without indexing or registering a
definition, and with indenting on the left for both the specification
and the @scheme[pre-flow]s.}
@defform[(specsubform maybe-literals datum pre-flow ...)]{
@ -272,18 +296,64 @@ The @scheme[pre-flow]s list is parsed as a flow that documents the
procedure. In this description, a reference to any identifier in
@scheme[datum] is typeset as a sub-form non-terminal.}
@defform[(specsubform/subs maybe-literals datum
([nonterm-id clause-datum ...+] ...)
pre-flow ...)]{
Like @scheme[specsubform], but with a grammar like
@scheme[defform/subs].}
@defform[(specspecsubform maybe-literals datum pre-flow ...)]{
Like @scheme[specsubform], but indented an extra level. Since using
@scheme[specsubform] within the body of @scheme[specsubform] already
nests indentation, @scheme[specspecsubform] is for extra indentation
without nesting a description.}
@defform[(specspecsubform/subs maybe-literals datum
([nonterm-id clause-datum ...+] ...)
pre-flow ...)]{
Like @scheme[specspecsubform], but with a grammar like
@scheme[defform/subs].}
@defform[(defparam id arg-id contract-expr-datum pre-flow ...)]{
Like @scheme[defproc], but for a parameter. The
@scheme[contract-expr-datum] serves as both the result contract on the
parameter and the contract on values supplied for the parameter. The
@scheme[arg-id] refers to the parameter argument in the latter case.}
@defform[(defboolparam id arg-id pre-flow ...)]{
Like @scheme[defparam], but the contract on a parameter argument is
@scheme[any/c], and the contract on the parameter result is
@scheme[boolean?].}
@defform[(defthing id contract-expr-datum pre-flow ...)]{
Like @scheme[defproc], but for a non-procedure binding.}
@defform/subs[(defstruct struct-name ([field-name contract-expr-datum] ...)
flag-keywords
pre-flow ...)
([struct-name id
(id super-id)])]{
(id super-id)]
[flag-keywords code:blank
#:immutable
(code:line #:inspector #f)
(code:line #:immutable #:inspector #f)])]{
Similar to @scheme[defform] or @scheme[defproc], but for a structure
definition.}
@defform/subs[(schemegrammar maybe-literals id clause-datum ...+)
([maybe-literals code:blank
(code:line #:literals (literal-id ...))])]{
@ -293,6 +363,7 @@ mentioned in a @scheme[clause-datum] is typeset as a non-terminal,
except for the identifiers listed as @scheme[literal-id]s, which are
typeset as with @scheme[scheme].}
@defform[(schemegrammar* maybe-literals [id clause-datum ...+] ...)]{
Like @scheme[schemegrammar], but for typesetting multiple productions
@ -301,8 +372,10 @@ at once, aligned around the @litchar{=} and @litchar{|}.}
@; ------------------------------------------------------------------------
@section{Various String Forms}
@defproc[(defterm [pre-content any/c] ...) element?]{Typesets the given
content as a defined term (e.g., in italic).}
@defproc[(defterm [pre-content any/c] ...) element?]{Typesets the
given content as a defined term (e.g., in italic). Consider using
@scheme[deftech] instead, though, so that uses of @scheme[tech] can
hyper-link to the definition.}
@defproc[(onscreen [pre-content any/c] ...) element?]{ Typesets the given
content as a string that appears in a GUI, such as the name of a
@ -317,30 +390,135 @@ as a file name (e.g., in typewriter font and in in quotes).}
@defproc[(exec [pre-content any/c] ...) element?]{Typesets the given content
as a command line (e.g., in typewriter font).}
@defproc[(envvar [pre-content any/c] ...) element?]{Typesets the given
content as an environment variable (e.g., in typewriter font).}
@defproc[(Flag [pre-content any/c] ...) element?]{Typesets the given
content as a flag (e.g., in typewriter font with a leading hyphen).}
@defproc[(DFlag [pre-content any/c] ...) element?]{Typesets the given
content a long flag (e.g., in typewriter font with two leading
hyphens).}
@defproc[(math [pre-content any/c] ...) element?]{The content form of
@scheme[pre-content] is transformed:
@itemize{
@item{Any immediate @scheme['rsquo] is converted to @scheme['prime].}
@item{Parentheses and sequences of decimal digits in immediate
strings are left as-is, but any other immediate string is
italicized.}
}
Extensions to @scheme[math] are likely, such as recognizing @litchar{_}
and @litchar{^} for subscripts and superscripts.}
@; ------------------------------------------------------------------------
@section[#:tag "scribble:manual:section-links"]{Section Links}
@section[#:tag "scribble:manual:section-links"]{Links}
@defproc[(secref [tag string?]) element?]{Inserts the hyperlinked
title of the section tagged @scheme[tag], but @scheme{aux-element}
items in the title content are omitted in the hyperlink label.}
@defproc[(secref [tag string?]) element?]{
@defproc[(seclink [tag string?] [pre-content any/c] ...) element?]{The content from
@scheme[pre-content] is hyperlinked to the section tagged @scheme[tag].}
Inserts the hyperlinked title of the section tagged @scheme[tag], but
@scheme{aux-element} items in the title content are omitted in the
hyperlink label.}
@defproc[(schemelink [id symbol?] [pre-content any/c] ...) element?]{The content from
@scheme[pre-content] is hyperlinked to the definition of @scheme[id].}
@defproc[(seclink [tag string?] [pre-content any/c] ...) element?]{
The content from @scheme[pre-content] is hyperlinked to the section
tagged @scheme[tag].}
@defproc[(schemelink [id symbol?] [pre-content any/c] ...) element?]{
The content from @scheme[pre-content] is hyperlinked to the definition
of @scheme[id].}
@defproc[(link [url string?] [pre-content any/c] ...) element?]{
The content from @scheme[pre-content] is hyperlinked to @scheme[url].}
@defproc[(elemtag [t tag?] [pre-content any/c] ...) element?]{
The tag @scheme[t] refers to the content form of
@scheme[pre-content].}
@defproc[(elemref [t tag?] [pre-content any/c] ...) element?]{
The content from @scheme[pre-content] is hyperlinked to @scheme[t],
which is normally defined using @scheme[elemtag].}
@defproc[(deftech [pre-content any/c] ...) element?]{
Produces an element for the content form of @scheme[pre-content], and
also defines a term that can be referenced elsewhere using
@scheme[tech].
The @scheme[content->string] result of the content form of
@scheme[pre-content] is used as a key for references, but normalized
as follows:
@itemize{
@item{A trailing ``ies'' is replaced by ``y''.}
@item{A trailing ``s'' is removed.}
@item{Consecutive hyphens and whitespaces are all replaced by a
single space.}
}
These normalization steps help support natural-language references
that differ slightly from a defined form. For example, a definition of
``bananas'' can be referenced with a use of ``banana''.}
@defproc[(tech [pre-content any/c] ...) element?]{
Produces an element for the content form of @scheme[pre-content], and
hyperlinks it to the definition of the content as established by
@scheme[deftech]. The content's string form is normalized in the same
way as for @scheme[deftech].
The hyperlink is relatively quiet, in that underlining in HTML output
appears only when the mouse is moved over the term.
In some cases, combining both natural-language uses of a term and
proper linking can require some creativity, even with the
normalization performed on the term. For example, if ``bind'' is
defined, but a sentence uses the term ``binding,'' the latter can be
linked to the former using @schemefont["@tech{bind}ing"].}
@defproc[(techlink [pre-content any/c] ...) element?]{
Like @scheme[tech], but the link is not a quiet. For example, in HTML
output, a hyperlink underline appears even when the mouse is not over
the link.}
@; ------------------------------------------------------------------------
@section{Indexing}
@defproc[(idefterm [pre-content any/c] ...) element?]{Combines
@scheme[as-index] and @scheme[defterm]. The content normally should be
plurarl, rather than singular.}
plural, rather than singular. Consider using @scheme[deftech],
instead, which always indexes.}
@defproc[(pidefterm [pre-content any/c] ...) element?]{Like
@scheme[idefterm], but plural: adds an ``s'' on the end of the content
for the index entry.}
for the index entry. Consider using @scheme[deftech], instead.}
@defproc[(indexed-file [pre-content any/c] ...) element?]{A
combination of @scheme[file] and @scheme[as-index], but where the sort
key for the index iterm does not include quotes.}
@defproc[(indexed-envvar [pre-content any/c] ...) element?]{A
combination of @scheme[envvar] and @scheme[as-index].}
@; ------------------------------------------------------------------------
@section{Miscellaneous}
@ -358,3 +536,6 @@ centered table with the @scheme[pre-flow] parsed by
@defproc[(commandline [pre-content any/c] ...) paragraph?]{Produces
an inset command-line example (e.g., in typewriter font).}
@defproc[(margin-code [pre-content any/c] ...) paragraph?]{Produces
a paragraph to be typeset in the margin instead of inlined.}

1
collects/scribblings/scribble/scribble.scrbl
View File

@ -88,3 +88,4 @@ information.
@include-section["basic.scrbl"]
@include-section["manual.scrbl"]
@include-section["eval.scrbl"]
@include-section["style.scrbl"]

101
collects/scribblings/scribble/struct.scrbl
View File

@ -8,12 +8,15 @@ A single document is represented as a @defterm{part}:
@itemize{
@item{A @defterm{part} is an instance of @scheme[part]; it has a
title @defterm{content}, an initial @defterm{flow}, and a list
of subsection @defterm{part}s. After the ``collect'' phase of
rendering, it also has @defterm{collected info}. An
@scheme[unnumbered-part] is the same as a @scheme[part], but it
isn't numbered.}
@item{A @defterm{part} is an instance of @scheme[part]; it has a list
of @defterm{tags} used as link targets, a title
@defterm{content}, a list of @defterm{elements} that supply
information during the ``collect'' phase but are not rendered,
an initial @defterm{flow}, and a list of subsection
@defterm{part}s. After the ``collect'' phase of rendering, it
also has @defterm{collected info}. A @scheme[styled-part]
includes an extra style flag. An @scheme[unnumbered-part] is
the same as a @scheme[styled-part], but it isn't numbered.}
@item{A @defterm{flow} is an instance of @scheme[flow]; it has a list
of @defterm{flow element}s.}
@ -61,9 +64,9 @@ A single document is represented as a @defterm{part}:
@item{A symbol element is either @scheme['mdash],
@scheme['ndash], @scheme['ldquo],
@scheme['lsquo], @scheme['rsquo], or
@scheme['rarr]; it is drawn as the
corresponding HTML entity.}
@scheme['lsquo], @scheme['rsquo],
@scheme['rarr], or @scheme['prime]; it is
drawn as the corresponding HTML entity.}
@item{An instance of @scheme[element] has a list of
@defterm{element}s plus a style. The style's
@ -83,7 +86,11 @@ A single document is represented as a @defterm{part}:
@item{An instance of @scheme[target-element] has a
@defterm{tag} to be referenced by
@scheme[link-element]s.}
@scheme[link-element]s. An instance of the
subtype @scheme[toc-target-element] is
treated like a kind of section label, to be
shown in the ``on this page'' table for HTML
output.}
@item{An instance of @scheme[index-element] has a
@defterm{tag} (as a target), a list of
@ -97,6 +104,10 @@ A single document is represented as a @defterm{part}:
@defterm{element}. The ``collect'' phase of
rendering ignores delayed flow elements.}
@item{An instance of @scheme[aux-element] is
excluded in the text of a link when it
appears in a referenced section name.}
}}}}
@item{A @defterm{delayed flow element} is an instance of
@ -119,21 +130,40 @@ Note that there's no difference between a part and a full document. A
particular source module just as easily defines a subsection
(incoprated via @scheme[include-section]) as a document.
@defstruct[part ([tag (or/c false/c tag?)]
@defstruct[part ([tags (listof tag?)]
[title-content (or/c false/c list?)]
[collected-info (or/c false/c collected-info?)]
[to-collect list?]
[flow flow?]
[parts (listof part?)])]{
}
@defstruct[(unnumbered-part part) ()]{
Each element of @scheme[tags] is actually wrapped as @scheme[`(part
,_tag)] as a target for links; functions like @scheme[seclink]
similarly insert the @scheme[`(part ,_tag)] wrapper.
}
@defstruct[(styled-part part) ([style any/c])]{
The currently recognized values for @scheme[style] are as follows:
@itemize{
@item{@scheme['toc] --- sub-parts of the part are rendered on separate
pages for multi-page HTML mode.}
@item{@scheme['index] --- the part represents an index.}
}
}
@defstruct[(unnumbered-part styled-part) ()]{
Although a section number is computed for an ``unnumbered'' section
during the ``collect'' phase, the number is not rendered.
}
@defstruct[flow ([paragraphs (listof flow-element?)])]{
@ -182,6 +212,10 @@ section, and the last argument correspond to global information
}
@defstruct[(toc-target-element target-element) ()]{
}
@defstruct[(link-element element) ([tag any/c]
[complain-if-fail? boolean?])]{
@ -192,6 +226,12 @@ section, and the last argument correspond to global information
[plain-seq (listof string?)]
[entry-seq list?])]{
The @scheme[plain-seq] specifies the keys for sorting, where the first
element is the main key, the second is a sub-key, etc. The
@scheme[entry-seq] list must have the same length, and it provides the
form of each key to render in the final document. See also
@scheme[index].
}
@defstruct[(aux-element element) ()]{
@ -202,7 +242,9 @@ example, @scheme[secref].
}
@defstruct[delayed-element ([render (any/c part? any/c . -> . list?)])]{
@defstruct[delayed-element ([render (any/c part? any/c . -> . list?)]
[sizer (-> any/c)]
[plain (-> any/c)])]{
The @scheme[render] procedure's arguments are the same as for
@scheme[delayed-flow-element]. Unlike @scheme[delayed-flow-element],
@ -211,12 +253,21 @@ on the first call. Furthemore, the element can be marshelled (e.g.,
for an index entry or a section-title entry) only if it has been
rendered first.
The @scheme[sizer] field is a procedure that produces a substitute
element for the delayed element for the purposes of determine the
element's width (see @scheme[element-width]).
The @scheme[plain] field is a procedure that produces a substitute for
the element when needed before the ``collect'' phase.
}
@defstruct[collected-info ([number (listof (or/c false/c integer?))]
[parent (or/c false/c part?)]
[info any/c])]{
Computed for each part by the ``collect'' phase.
}
@defproc[(flow-element? [v any/c]) boolean?]{
@ -227,18 +278,28 @@ Returns @scheme[#t] if @scheme[v] is a @scheme[paragraph],
}
@defproc[(tag? [v any/c]) boolean?]{
Returns @scheme[#t] if @scheme[v] is acceptable as a link tag,
@scheme[#f], otherwise. Currently, an acceptable tag is either a
string or a list containing a symbol and a string.
string or a list containing a symbol and a string.}
}
@defproc[(content->string (content list?)) string?]{
@defproc*[([(content->string (content list?)) string?]
[(content->string (content list?) (p part?) (info any/c)) string?])]{
Converts a list of elements to a single string (essentially
rendering the content as ``plain text'').
}
If @scheme[p] and @scheme[info] arguments are not supplied, then a
pre-``collect'' substitute is obtained for delayed
elements. Otherwise, the two arguments are used to force the delayed
element (if it has not been forced already).}
@defproc*[([(element->string (element any/c)) string?]
[(element->string (element any/c) (p part?) (info any/c)) string?])]{
Like @scheme[content->string], but for a single element.
}

70
collects/scribblings/scribble/style.scrbl Normal file
View File

@ -0,0 +1,70 @@
#reader(lib "docreader.ss" "scribble")
@require[(lib "manual.ss" "scribble")]
@require["utils.ss"]
@title[#:tag "reference-style"]{PLT Reference Style Guide}
@italic{Notes toward an eventual guide chapter...}
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
description will often start with ``Produces.'' Refer to arguments by
name.
Use @schemeidfont{id} or something that ends @schemeidfont{-id} in a
syntactic form to mean an identifier, not @schemeidfont{identifier},
@schemeidfont{name}, or @schemeidfont{symbol}. Similarly, use
@schemeidfont{expr} or something that ends @schemeidfont{-expr} for an
expression position within a syntactic form. Use @schemeidfont{body}
for a form (definition or expression) in an internal-definition
position.
Break up HTML documents into multiple pages by using the @scheme['toc]
section style in combination with
@scheme[local-table-of-contents]. The @scheme[local-table-of-contents]
should go after a short introduction, if any. In some cases, a longer
introduction is better placed after the
@scheme[local-table-of-contents] call, especially if the contents are
short.
Favor hyperlinks installed by @scheme[scheme] instead of explicit
section links produced by @scheme[secref]. In particular, there's
rarely a need to have both links (e.g., ``see @scheme[scheme] in
@secref["scribble:manual:code"]'').
Link tags are resolved relative to surrounding sections, but if you
think anyone will ever refer to a link targer, try to pick a tag that
will be globally unique. For example, all of the section tags in the
PLT Scheme reference start with @litchar["mz:"].
Pay attention to the difference between identifiers and meta-variables
when using @scheme[scheme], especially outside of @scheme[defproc] or
@scheme[defform]. Prefix a meta-variable with @litchar{_}; for
example,
@verbatim[" @scheme[(rator-expr rand-expr ...)]"]
would be the wrong way to refer to the grammar of a function call,
because it produces @scheme[(rator-expr rand-expr ...)], where
@schemeidfont{rator-expr} and @schemeidfont{rand-expr} are
typeset as variables. The correct description is
@verbatim[" @scheme[(_rator-expr _rand-expr ...)]"]
which produces @scheme[(_rator-expr _rand-expr ...)], where
@schemeidfont{rator-expr} @schemeidfont{rand-expr} are typeset as
meta-variables. The @scheme[defproc], @scheme[defform], @|etc| forms
greatly reduce this burden in description, since they automatically
set up meta-variable typesetting for non-literal identifiers.
To typeset an identifier with no particular interpretation---syntax,
variable, meta-variable, etc.---use @scheme[schemeidfont] (e.g., as in
@schemeidfont{rand-expr} above). Otherwise, use @scheme[litchar],
not merely @scheme[schemefont] or @scheme[verbatim], to refer to a
specific sequence of characters.
Use American style for quotation marks and punctuation at the end of
quotation marks (i.e., a sentence-terminating period goes inside the
quotation marks). Of course, this rule does not apply for quotation
marks that are part of code.