catch up scribble reference

svn: r7051

original commit: 1b6483bc36b16f86b306ab6334cc1b44d1ee08d0

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)))

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?)]
+   [part-index-decl ([plain-seq (listof string?)]
-                        [entry-seq list?])])
+                     [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)
+                                             (part-index-decl-plain-seq k)
-                                             (section-index-decl-entry-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)))

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)])

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
+         title-decl?]{
- be picked up by @scheme[decode] or @scheme[decode-part].  The
+
- @scheme[pre-content]s list is parsed with @scheme[decode-content] for
+Generates a @scheme[title-decl] to be picked up by @scheme[decode] or
- the title content. If @scheme[tag] is @scheme[#f], a tag string is
+@scheme[decode-part].  The @scheme[pre-content]s list is parsed with
- generated automatically from the content. The tag string is combined
+@scheme[decode-content] for the title content. If @scheme[tag] is
- with the symbol @scheme['part] to form the full tag.}
+@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
+Returns a delayed flow element that expands to a table of contents for
- currently spans the entire enclosing document.
+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.}

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[index-section-decl] (that preceed any sub-part) add index
-@scheme[section] trigger are used as-is as subsections, and instances
+entries that point to the section. Instances of @scheme[part-start] at
-of @scheme[paragraph] and other flow-element datatypes are used as-is
+level 0 trigger sub-part parsing. Instances of @scheme[section]
-in the enclosing flow.
+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].

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
+to document a procedure named @scheme[id]. The @scheme[id] is indexed,
-registered so that @scheme[scheme]-typeset uses of the identifier
+and it also registered so that @scheme[scheme]-typeset uses of the
-(with the same lexical binding) are hyperlinked to this documentation.
+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
+@scheme[id] is indexed, and it is also registered so that
-identifier (with the same lexical binding) are hyperlinked to this
+@scheme[scheme]-typeset uses of the identifier (with the same lexical
-documentation.
+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)
+@defform[(defform/subs maybe-literals (id . datum)
-                ([nonterm-id clause-datum ...+] ...)
+           ([nonterm-id clause-datum ...+] ...)
-                pre-flow ...)
+           pre-flow ...)]{
-              ([maybe-literals code:blank
+
-                               (code:line #:literals (literal-id ...))])]{
 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
+@defform[(defform/none datum pre-flow ...)]{
-indenting on the left for both the specification and the
+
-@scheme[pre-flow]s.}
+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
+@defproc[(defterm [pre-content any/c] ...) element?]{Typesets the
-content as a defined term (e.g., in italic).}
+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
+@defproc[(secref [tag string?]) element?]{
-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
+Inserts the hyperlinked title of the section tagged @scheme[tag], but
-@scheme[pre-content] is hyperlinked to the section tagged @scheme[tag].}
+@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.}

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"]

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
+ @item{A @defterm{part} is an instance of @scheme[part]; it has a list
-       title @defterm{content}, an initial @defterm{flow}, and a list
+       of @defterm{tags} used as link targets, a title
-       of subsection @defterm{part}s.  After the ``collect'' phase of
+       @defterm{content}, a list of @defterm{elements} that supply
-       rendering, it also has @defterm{collected info}. An
+       information during the ``collect'' phase but are not rendered,
-       @scheme[unnumbered-part] is the same as a @scheme[part], but it
+       an initial @defterm{flow}, and a list of subsection
-       isn't numbered.}
+       @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['lsquo], @scheme['rsquo],
-                         @scheme['rarr]; it is drawn as the
+                         @scheme['rarr], or @scheme['prime]; it is
-                         corresponding HTML entity.}
+                         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?)])]{
 
-}
+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[(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.
+}

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.