commit 648facb9e480047b7d143cc8e87ea25d2dcdafc0
parent f7803f005e78743bd3d9606e55822909938c7781
Author: Matthew Flatt <mflatt@racket-lang.org>
Date: Wed, 8 Aug 2007 02:45:25 +0000
catch up scribble reference
svn: r7051
original commit: 1b6483bc36b16f86b306ab6334cc1b44d1ee08d0
Diffstat:
9 files changed, 434 insertions(+), 83 deletions(-)
diff --git a/collects/scribble/basic.ss b/collects/scribble/basic.ss
@@ -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)))
diff --git a/collects/scribble/decode.ss b/collects/scribble/decode.ss
@@ -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)))
diff --git a/collects/scribble/manual.ss b/collects/scribble/manual.ss
@@ -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)])
diff --git a/collects/scribblings/scribble/basic.scrbl b/collects/scribblings/scribble/basic.scrbl
@@ -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.}
diff --git a/collects/scribblings/scribble/decode.scrbl b/collects/scribblings/scribble/decode.scrbl
@@ -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].
diff --git a/collects/scribblings/scribble/manual.scrbl b/collects/scribblings/scribble/manual.scrbl
@@ -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[(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[(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[(seclink [tag string?] [pre-content any/c] ...) element?]{The content from
-@scheme[pre-content] is hyperlinked to the section tagged @scheme[tag].}
+@defproc[(elemref [t tag?] [pre-content any/c] ...) element?]{
-@defproc[(schemelink [id symbol?] [pre-content any/c] ...) element?]{The content from
-@scheme[pre-content] is hyperlinked to the definition of @scheme[id].}
+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.}
diff --git a/collects/scribblings/scribble/scribble.scrbl b/collects/scribblings/scribble/scribble.scrbl
@@ -88,3 +88,4 @@ information.
@include-section["basic.scrbl"]
@include-section["manual.scrbl"]
@include-section["eval.scrbl"]
+@include-section["style.scrbl"]
diff --git a/collects/scribblings/scribble/struct.scrbl b/collects/scribblings/scribble/struct.scrbl
@@ -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,20 +130,39 @@ 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?)])]{
+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[(unnumbered-part part) ()]{
+@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[(styled-part part) ([style any/c])]{
+}
+
+@defstruct[(unnumbered-part styled-part) ()]{
+
+Although a section number is computed for an ``unnumbered'' section
+during the ``collect'' phase, the number is not rendered.
}
@@ -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.
+}
diff --git a/collects/scribblings/scribble/style.scrbl b/collects/scribblings/scribble/style.scrbl
@@ -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.
