bkyk8rc3zvpnsf5inmcqq4n3k98cv6hj-my-site-hyper-literate-git.test.suzanne.soy-0.0.1

core.scrbl (80012B)

---

 #lang scribble/doc
 @(require scribble/manual 
           (except-in "utils.rkt" url)
           "struct-hierarchy.rkt" 
           (only-in scribble/eval as-examples)
           (for-label scribble/manual-struct
                      racket/serialize
                      file/convertible
                      setup/main-collects
                      scriblib/render-cond
                      xml/xexpr
                      net/url-structs
                      scriblib/figure
                      (only-in scribble/html-render render-mixin)))
 
 @title[#:tag "core"]{Structures And Processing}
 
 @defmodule[scribble/core]
 
 A document is represented as a @techlink{part}, as described in
  @secref["parts"]. This representation is intended to be
  independent of its eventual rendering, and it is intended to be
  immutable; rendering extensions and specific data in a document can
  collude arbitrarily, however.
 
 A document is processed in four passes:
 
 @itemlist[
 
  @item{The @deftech{traverse pass} traverses the document content in
        document order so that information from one part of a document
        can be communicated to other parts of the same document. The
        information is transmitted through a symbol-keyed mapping that
        can be inspected and extended by @racket[traverse-element]s and
        @racket[traverse-block]s in the document. The @tech{traverse
        pass} iterates the traversal until it obtains a fixed point
        (i.e., the mapping from one iteration is unchanged from the
        previous iteration).}
 
  @item{The @deftech{collect pass} globally collects information in the
        document that can span documents that are built at separate
        times, such as targets for hyperlinking.}
 
  @item{The @deftech{resolve pass} matches hyperlink references
        with targets and expands delayed elements (where the expansion
        should not contribute new hyperlink targets).}
 
  @item{The @deftech{render pass} generates the result document.}
 
 ]
 
 None of the passes mutate the document representation. Instead, the
  @tech{traverse pass}, @tech{collect pass}, and @tech{resolve pass}
  accumulate information in a side hash table, @racket[collect-info]
  table, and @racket[resolve-info] table. The @tech{collect pass} and
  @tech{resolve pass} are effectively specialized version of
  @tech{traverse pass} that work across separately built documents.
 
  
 @; ------------------------------------------------------------------------
 
 @section[#:tag "parts"]{Parts, Flows, Blocks, and Paragraphs}
 
 This diagram shows the large-scale structure of the
 type hierarchy for Scribble documents. A box represents
 a struct or a built-in Racket type; for example @racket[part] is a struct.
 The bottom portion of a box shows the fields; for example
 @racket[part] has three fields, @racket[title], @racket[blocks], 
 and @racket[subparts].
 The substruct relationship
 is shown vertically with navy blue lines connected by a triangle;
 for example, a @racket[compound-paragraph] is a @racket[block]. 
 The types of values on fields are shown via dark red lines in the diagram.
 Doubled lines represent lists and tripled lines represent lists
 of lists; for example, the @racket[blocks] field of 
 @racket[compound-paragraph] is a list of @racket[blocks].
 Dotted lists represent functions that compute elements of
 a given field; for example, the @racket[block] field of 
 a @racket[traverse-block] struct is a function that
 computes a @racket[block]. 
 
 The diagram is not completely
 accurate: a @racket[table] may have @racket['cont]
 in place of a block in its @racket[cells] field, and
 the types of fields are only shown if they are other structs
 in the diagram.
 A prose description with more detail follows the diagram.
 
 @(mk-diagram)
 
 A @deftech{part} is an instance of @racket[part]; among other things,
  it has a title @techlink{content}, an initial @techlink{flow}, and a
  list of subsection @techlink{parts}.  There is no difference between
  a part and a full document; a particular source module just as easily
  defines a subsection (incorporated via @racket[include-section]) as a
  document.
 
 A @deftech{flow} is a list of @techlink{blocks}.
 
 A @deftech{block} is either a @techlink{table}, an
  @techlink{itemization}, a @techlink{nested flow}, a
  @techlink{paragraph}, a @techlink{compound paragraph}, a
  @techlink{traverse block}, or a @techlink{delayed block}.
 
 @itemize[
 
        @item{A @deftech{table} is an instance of @racket[table]; it
              has a list of list of @techlink{blocks} corresponding to
              table cells.}
 
        @item{A @deftech{itemization} is an instance of @racket[itemization];
              it has a list of @techlink{flows}.}
 
        @item{A @deftech{nested flow} is an instance of
              @racket[nested-flow]; it has a @tech{flow} that
              is typeset as sub-flow.}
 
        @item{A @deftech{paragraph} is an instance of
              @racket[paragraph]; it has a @tech{content}:
 
              @itemize[
 
              @item{A @deftech{content} can be a string, one of a few
                    symbols, a convertible value in the sense of @racket[convertible?],
                    an instance of @racket[element] (possibly
                    @racket[link-element], etc.), a @racket[multiarg-element], a
                    @techlink{traverse element}, a @techlink{part-relative element}, a
                    @techlink{delayed element}, or a list of content.
 
                    @itemize[
 
                    @item{A string is included in the result
                          document verbatim, except for space, and
                          unless the content's enclosing @tech{style} is
                          @racket['hspace]. In a style other than
                          @racket['hspace], consecutive spaces in the
                          output may be collapsed togther or replaced
                          with a line break. In the style
                          @racket['hspace], all text is converted to
                          uncollapsible spaces that cannot be broken
                          across lines.}
 
                    @item{A symbol content is either @racket['mdash],
                          @racket['ndash], @racket['ldquo],
                          @racket['lsquo], @racket['rdquo], @racket['rsquo], @racket['larr],
                          @racket['rarr], or @racket['prime]; it is
                          rendered as the corresponding HTML entity
                          (even for Latex output).}
 
                    @item{A convertible value in the sense of @racket[convertible?]
                          is used in a renderer-specific way, but values convertible
                          to @racket['text] renders the same as the resulting
                          string. If a renderer is not able to convert the value
                          to a known format, the value is converted to a string
                          using @racket[write].}
 
                    @item{An instance of @racket[element] has a
                          @techlink{content} plus a @tech{style}. The style's
                          interpretation depends on the renderer, but it
                          can be one of a few special symbols (such as
                          @racket['bold]) that are recognized by all
                          renderers.}
 
                    @item{An instance of @racket[link-element] has a
                          @techlink{tag} for the target of the link.}
 
                    @item{An instance of @racket[target-element] has a
                          @techlink{tag} to be referenced by
                          @racket[link-element]s. An instance of the
                          subtype @racket[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 @racket[index-element] has a
                          @techlink{tag} (as a target), a list of
                          strings for the keywords (for sorting and
                          search), and a list of @techlink{contents} to
                          appear in the end-of-document index.}
 
                    @item{An instance of @racket[image-element]
                          incorporates an image from a file into the rendered
                          document.}
 
                    @item{An instance of @racket[multiarg-element]
                          combines a style with a list of content,
                          where the style corresponds to a rendered
                          command that takes multiple arguments.}
 
                    @item{An instance of @racket[collect-element] has a
                          procedure that is called in the
                          @techlink{collect pass} of document
                          processing to record information used by
                          later passes.}
 
                    @item{A @deftech{traverse element} is an instance
                          of @racket[traverse-element], which
                          ultimately produces content, but can
                          accumulate and inspect information in the
                          @tech{traverse pass}.}
 
                    @item{A @deftech{part-relative element} is an
                          instance of @racket[part-relative-element],
                          which has a procedure that is called in the
                          @techlink{collect pass} of document
                          processing to obtain @defterm{content}. When the
                          part-relative element's procedure is called,
                          collected information is not yet available,
                          but information about the enclosing parts is
                          available.}
 
                    @item{A @deftech{delayed element} is an instance of
                          @racket[delayed-element], which has a
                          procedure that is called in the
                          @techlink{resolve pass} of document
                          processing to obtain @defterm{content}.}
 
                    @item{An instance of @racket[render-element] has a
                          procedure that is called in the
                          @techlink{render pass} of document
                          processing.}
 
              ]}]}
 
        @item{A @deftech{compound paragraph} is an instance of
              @racket[compound-paragraph]; like @racket[blockquote], it
              has list of @tech{blocks}, but the blocks are typeset as
              a single paragraph (e.g., no indentation after the first
              block) instead of inset.}
 
        @item{A @deftech{traverse block} is an instance of
              @racket[traverse-block], which ultimately produces
              another block, but can accumulate and inspect information
              during the @tech{traverse pass}.}
 
        @item{A @deftech{delayed block} is an instance of
              @racket[delayed-block], which has a procedure that
              is called in the @techlink{resolve pass} of document
              processing to obtain a @defterm{block}.}
 
 ]
 
 @history[#:changed "1.23" @elem{Changed the handling of @racket[convertible?]
                                 values to recognize a @racket['text] conversion
                                 and otherwise use @racket[write].}]
 
 @; ------------------------------------------------------------------------
 
 @section[#:tag "tags"]{Tags}
 
 A @deftech{tag} is a list containing a symbol and either a string, a
 @racket[generated-tag] instance, or an arbitrary list. The symbol
 effectively identifies the type of the tag, such as @racket['part] for
 a tag that links to a part, or @racket['def] for a Racket function
 definition. The symbol also effectively determines the interpretation
 of the second half of the tag.
 
 A part can have a @deftech{tag prefix}, which is effectively added
 onto the second item within each tag whose first item is
 @racket['part], @racket['tech], or @racket['cite], or whose second
 item is a list that starts with @racket['prefixable]:
 
 @itemlist[
 
  @item{The prefix is added to a string second item by creating a list
        containing the prefix and string.}
 
  @item{The prefix is added to a list second item after @racket['part],
        @racket['tech], or @racket['cite] using @racket[cons].}
 
  @item{The prefix is added to a second item that starts
        @racket['prefixable] by adding it to the list after
        @racket['prefixable].}
 
  @item{A prefix is not added to a  @racket[generated-tag] item.}
 
 ]
 
 The prefix is used for reference outside the part, including the use
 of tags in the part's @racket[tags] field. Typically, a document's
 main part has a tag prefix that applies to the whole document;
 references to sections and defined terms within the document from
 other documents must include the prefix, while references within the
 same document omit the prefix. Part prefixes can be used within a
 document as well, to help disambiguate references within the document.
 
 Some procedures accept a ``tag'' that is just the string part of the
 full tag, where the symbol part is supplied automatically. For
 example, @racket[section] and @racket[secref] both accept a string
 ``tag'', where @racket['part] is implicit.
 
 The @racketmodname[scribble/tag] library provides functions for constructing
 @tech{tags}.
 
 @; ------------------------------------------------------------------------
 
 @section[#:tag "style"]{Styles}
 
 A @deftech{style} combines a @tech{style name} with a list of
 @tech{style properties} in a @racket[style] structure. A @deftech{style name}
 is either a string, symbol, or @racket[#f]. A @deftech{style property} can be
 anything, including a symbol or a structure such as
 @racket[color-property].
 
 A style has a single @tech{style name}, because the name typically
 corresponds to a configurable instruction to a renderer. For example,
 with Latex output, a string style name corresponds to a Latex command
 or environment. For more information on how string style names
 interact with configuration of a renderer, see
 @secref["config"]. Symbolic style names, meanwhile, provide a simple
 layer of abstraction between the renderer and documents for widely
 supported style; for example, the @racket['italic] style name is
 supported by all renderers.
 
 @tech{Style properties} within a style compose with style names and other
 properties. Again, symbols are often used for properties that are directly
 supported by renderers. For example, @racket['unnumbered] style
 property for a @tech{part} renders the part without a section number.
 Many properties are renderer-specific, such as a @racket[hover-property]
 structure that associates text with an element to be shown in an
 HTML display when the mouse hovers over the text.
 
 @; ------------------------------------------------------------------------
 
 @section[#:tag "passes"]{Collected and Resolved Information}
 
 The @techlink{collect pass}, @techlink{resolve pass}, and
 @techlink{render pass} processing steps all produce information that
 is specific to a rendering mode. Concretely, the operations are all
 represented as methods on a @racket[render<%>] object.
 
 The result of the @method[render<%> collect] method is a
 @racket[collect-info] instance. This result is provided back as an
 argument to the @method[render<%> resolve] method, which produces a
 @racket[resolve-info] value that encapsulates the results from both
 iterations. The @racket[resolve-info] value is provided back to the
 @method[render<%> resolve] method for final rendering.
 
 Optionally, before the @method[render<%> resolve] method is called,
 serialized information from other documents can be folded into the
 @racket[collect-info] instance via the @method[render<%>
 deserialize-info] method. Other methods provide serialized information
 out of the collected and resolved records.
 
 During the @techlink{collect pass}, the procedure associated with a
 @racket[collect-element] instance can register information with
 @racket[collect-put!].
 
 During the @techlink{resolve pass}, collected information for a part
 can be extracted with @racket[part-collected-info], which includes a
 part's number and its parent part (or @racket[#f]). More generally,
 the @racket[resolve-get] method looks up information previously
 collected. This resolve-time information is normally obtained by the
 procedure associated with a @techlink{delayed block} or
 @techlink{delayed element}.
 
 The @racket[resolve-get] information accepts both a @racket[part] and
 a @racket[resolve-info] argument. The @racket[part] argument enables
 searching for information in each enclosing part before sibling parts.
 
 @; ------------------------------------------------------------------------
 
 @section{Structure Reference}
 
 @defstruct[part ([tag-prefix (or/c #f string?)]
                  [tags (listof tag?)]
                  [title-content (or/c #f list?)]
                  [style style?]
                  [to-collect list?]
                  [blocks (listof block?)]
                  [parts (listof part?)])]{
 
 The @racket[tag-prefix] field determines the optional @techlink{tag
 prefix} for the part.
 
 The @racket[tags] indicates a list of @techlink{tags} that each link
 to the section. Normally, @racket[tags] should be a non-empty list, so
 that hyperlinks can target the section.
 
 The @racket[title-content] field holds the part's title, if any.
 
 For the @racket[style] field, the currently recognized symbolic style
 names are as follows:
 
 @itemize[
 
  @item{@indexed-racket['index] --- The part represents an index.}
 
 ]
 
 The recognized @tech{style properties} are as follows:
 
 @itemize[
 
  @item{@indexed-racket['unnumbered] --- A section number is not computed or
        rendered for the section.}
 
  @item{@indexed-racket['hidden-number] --- A section number is computed for
        the section, but it is not rendered as part of the section name.}
 
  @item{@indexed-racket['toc-hidden] --- The part title is not shown in tables
        of contents, including in ``on this page'' boxes. For Latex
        rendering, the part title is omitted only if it is unnumbered
        or has a hidden number.}
 
  @item{@indexed-racket['hidden] --- The part title is not shown; for Latex
        output, the part title is not shown only if its is empty, and
        in that case, it is also excluded from tables of contents.  The
        @racket['toc-hidden] @tech{style property} usually should be included with
        @racket['hidden] (for consistency in non-Latex output).}
 
  @item{@indexed-racket['grouper] --- The part is numbered with a Roman
        numeral, by default, and its subsections continue numbering as
        if they appeared in the preceeding part. In other words, the
        part acts like a ``part'' in a book where chapter numbering is
        continuous across parts.}
 
  @item{@tech{numberer} --- A @tech{numberer} created with
        @racket[make-numberer] determines a representation of the
        part's section number as an extension of it's parent's number.
        A @tech{numberer} overrides the default representation, which
        is a natural number or (in the case of an accompanying
        @racket['grouper] property) a Roman numeral. If a
        @racket['unnumbered] property is also present, a
        @tech{numberer} property is ignored.}
 
  @item{@indexed-racket['toc] --- Sub-parts of the part are rendered on separate
        pages for multi-page HTML mode.}
 
  @item{@indexed-racket['non-toc] --- Initial sub-parts of the part are
        @emph{not} rendered on separate pages for multi-page HTML
        mode; this @tech{style property} applies only to the main part.}
 
  @item{@indexed-racket['reveal] --- Shows sub-parts when this part is
        displayed in a table-of-contents panel in HTML output (which
        normally shows only the top-level sections).}
 
  @item{@indexed-racket['quiet] --- In HTML output and most other output modes,
        hides entries for sub-parts of this part in a
        @racket[table-of-contents] or @racket[local-table-of-contents]
        listing except when those sub-parts are top-level entries in
        the listing.}
 
  @item{@indexed-racket['no-toc+aux] --- As a @tech{style property} for
        the main part of a rendered page, causes the HTML output to not
        include a margin box for the main table of contents, ``on this
        page'', or tables with the @racket['aux] style property. The
        @racket['no-toc+aux] property effectively implies
        @racket['no-toc] and @racket['no-sidebar], but also suppresses
        @racket['aux] tables.}
 
  @item{@indexed-racket['no-toc] --- As a @tech{style property} for the main part of a
        rendered page, causes the HTML output to not include a margin box
        for the main table of contents; the ``on this page'' box that
        contains @racket[toc-element] and @racket[toc-target-element]
        links (and that only includes an ``on this page'' label for
        multi-page documents) takes on the location and color of the
        main table of contents, instead.}
 
  @item{@indexed-racket['no-sidebar] --- As a @tech{style property} for the main part of a
        document, causes the HTML output to not include an ``on this 
        page'' margin box.}
 
  @item{@indexed-racket['no-index] --- Has no effect as a @tech{style
        property} on a @racket[part], but as a style property on a
        @racket[title] or @racket[part-start] that provides a
        @racket[part]'s style via @racket[decode], the
        @racket['no-index] @tech{style property} cause @racket[decode]
        to skip the generation of an entry for the part's title in the
        document index.}
 
  @item{@racket[document-version] structure --- A version number for
        this part and its sub-parts (except as overridden). When it is
        not @racket[""] may be used when rendering a document; at a
        minimum, a non-@racket[""] version is rendered when it is
        attached to a part representing the whole document. The default
        version for a document is @racket[(version)]. In rendered form,
        the version is normally prefixed with the word ``Version,'' but
        this formatting can be controlled by overriding
        @tt{.version:before} and/or @tt{.versionNoNav:before} in CSS
        for HTML rendering or by redefining the @tt{\SVersionBefore}
        macro for Latex rendering (see @secref["config"]).}
 
  @item{@racket[document-date] structure --- A date for the part,
        normally used on a document's main part for for Latex
        output. The default date for a document is @racket[#f], which
        avoids explicitly specifying a date at the Latex level, so that
        the current date is used as the document date. Set the date to
        @racket[""] to suppress a date in an output document.}
 
   @item{@racket[body-id] structure --- Generated HTML uses the given
         string @tt{id} attribute of the @tt{<body>} tag; this @tech{style property} can
         be set separately for parts that start different HTML pages,
         otherwise it is effectively inherited by sub-parts; the
         default is @racket["scribble-racket-lang.org"], but
         @exec{raco setup} installs @racket["doc-racket-lang.org"] as the
         @tt{id} for any document that it builds.}
 
  @item{@racket[attributes] structure --- Provides additional HTML
        attributes for the @tt{<html>} tag when the part corresponds to
        its own HTML page.}
 
  @item{@racket[head-extra] structure --- Provides additional HTML
        content for the @tt{<head>} tag when the part corresponds to
        its own HTML page.}
 
  @item{@racket[color-property] structure --- For HTML, applies a color
        to the part title.}
 
  @item{@racket[background-color-property] structure --- For HTML,
        applies a color to the background of the part title.}
 
  @item{@racket[hover-property] structure --- For HTML, adds a text
        label to the title to be shown when the mouse hovers over
        it.}
            
  @item{@racket[render-convertible-as] structure --- For HTML, controls
         how objects that subscribe to the @racketmodname[file/convertible]
         protocol are rendered.}
 
  @item{@racket[document-source] structure --- For HTML, provides a
         module path for the part's source. Clicking on an HTML section
         title generated for the part or its sub-parts may show the
         module path plus a section-tag string, so that the user can
         create a reference to the section.}
 
  @item{@racket[link-render-style] structure --- Determines the default
        rendering of links to sections or other destinations within the
        section. See also @racket[link-element] and
        @racket[current-link-render-style].}
 
  @item{@racket['enable-index-merge] --- On an index parts or one of
        its enclosing parts for Latex output, causes index entries to
        be merged when they have the same content, with multiple
        references for the same entry combined with @ltx{Smanypageref}.
        The @ltx{Smanypageref} Latex macro must be redefined to accept
        multiple @litchar{,}-separated labels and generate a suitable set of
        references. See also @racketmodname[scriblib/book-index].}
 
 ]
 
 The @racket[to-collect] field contains @techlink{content} that is
 inspected during the @techlink{collect pass}, but ignored in later
 passes (i.e., it doesn't directly contribute to the output).
 
 The @racket[blocks] field contains the part's initial flow (before
 sub-parts).
 
 The @racket[parts] field contains sub-parts.
 
 @history[#:changed "1.25" @elem{Added @racket['no-index] support.}
          #:changed "1.26" @elem{Added @racket[link-render-style] support.}
          #:changed "1.27" @elem{Added @racket['no-toc+aux] support.}]}
 
 
 @defstruct[paragraph ([style style?] [content content?])]{
 
 A @techlink{paragraph} has a @tech{style} and a @tech{content}.
 
 For the @racket[style] field, a string @tech{style name} corresponds
 to a CSS class for HTML output or a macro for Latex output (see
 @secref["extra-style"]). The following symbolic @tech{style names} are
 recognized:
 
 @itemize[
 
  @item{@indexed-racket['author] --- Typeset as the author of a document.  Such
        paragraphs normally should appear only in the initial flow of a
        @racket[part] for a document, where they are treated specially
        by the Latex renderer by moving the author information to the
        title.}
 
  @item{@indexed-racket['pretitle] --- Typeset before the title of the
        enclosing part.}
 
  @item{@indexed-racket['wraps] --- Like a @racket[#f] @tech{style name}, but not
        @tech{boxable} in the sense of @racket[box-mode] for Latex output.}
 
 ]
 
 When a paragraph's style is @racket[#f], then it is @tech{boxable} in the
 sense of @racket[box-mode] for Latex output.
 
 The currently recognized @tech{style properties} are as follows:
 
 @itemize[
 
  @item{@indexed-racket['omitable] --- When a table cell contains a single
        @racket[paragraph] with the @racket['omitable] @tech{style property},
        then when rendering to HTML, no @tt{<p>} tag wraps the cell
        content.}
 
  @item{@indexed-racket['div] --- Generates @tt{<div>} HTML output instead of
        @tt{<p>} (unless a @racket[alt-tag] property is provided).}
 
  @item{@racket[alt-tag] structure --- Generates the indicated HTML tag
        instead of @tt{<p>} or @tt{<div>}.}
 
  @item{@racket[attributes] structure --- Provides additional HTML
        attributes for the @tt{<p>}, @tt{<div>}, or alternate tag.}
 
  @item{@indexed-racket['never-indents] --- For Latex and @tech{compound
        paragraphs}; see @racket[compound-paragraph].}
 
  @item{@racket[box-mode] structure --- For Latex output, uses an alternate
        rendering form for @tech{boxing contexts} (such as a table cell); see
        @racket[box-mode].}
 
 ]}
 
 
 @defstruct[table ([style style?]
                   [blockss (listof (listof (or/c block? 'cont)))])]{
 
 See also the @racket[tabular] function.
 
 A @techlink{table} has, roughly, a list of list of blocks. A cell in
 the table can span multiple columns by using @racket['cont] instead of
 a block in the following columns (i.e., for all but the first in a set
 of cells that contain a single block).
 
 Within @racket[style], a string @tech{style name} corresponds to a CSS
 class for HTML output or an environment for Latex output (see
 @secref["extra-style"]). The following symbolic style names are also
 recognized:
 
 @itemize[
 
  @item{@indexed-racket['boxed] --- Renders as a definition.
        This style name is not intended for use on a table that is
        nested within a @racket['boxed] table; nested uses may look
        right for some renders of the style but not others.}
 
  @item{@indexed-racket['centered] --- Centers HTML output horizontally.}
 
  @item{@indexed-racket['block] --- Prevents pages breaks in Latex output.}
 
 ]
 
 The following @tech{style properties} are currently recognized:
 
 @itemize[
 
  @item{@racket[table-columns] structure --- Provides column-specific
        styles, but only @racket[column-attributes] properties (if any)
        are used if a @racket[table-cells] structure is included as a
        @tech{style property}. See @racket[table-cells] for information
        about how a column style is used for each cell.}
 
  @item{@racket[table-cells] structure --- Provides cell-specific
        styles. See @racket[table-cells] for information about how the
        styles are used.}
 
  @item{@racket[attributes] structure --- Provides additional HTML
        attributes for the @tt{<table>} tag.}
 
  @item{@indexed-racket['aux] --- For HTML, include the table in the
        table-of-contents display for the enclosing part.}
 
  @item{@indexed-racket['never-indents] --- For Latex and @tech{compound
        paragraphs}; see @racket[compound-paragraph].}
 
 ]
 
 For Latex output, a paragraph as a cell value is not automatically
 line-wrapped, unless a vertical alignment is specified for the cell
 through a @racket[table-cells] or @racket[table-columns]
 @tech{style property}. To get a line-wrapped paragraph, use a
 @racket[compound-paragraph] or use an element with a string style and
 define a corresponding Latex macro in terms of @ltx{parbox}. For Latex
 output of blocks in the flow that are @racket[nested-flow]s,
 @racket[itemization]s, @racket[compound-paragraph]s, or
 @racket[delayed-block]s, the block is wrapped with @ltxe{minipage} using
 @ltx{linewidth} divided by the column count as the width.}
 
 
 @defstruct[itemization ([style style?]
                         [blockss (listof (listof block?))])]{
 
 A @techlink{itemization} has a @tech{style} and a list of @tech{flows}.
 
 In @racket[style], a string @tech{style name} corresponds to a CSS
 class for HTML output or a macro for Latex output (see
 @secref["extra-style"]). In addition, the following symbolic style
 names are recognized:
 
 @itemize[
 
  @item{@indexed-racket['compact] --- Reduces space between items.}
 
  @item{@indexed-racket['ordered] --- Generates @tt{<ol>} HTML output instead
        of @tt{<ul>} or an Latex enumeration instead of an
        itemization.}
 ]
 
 The following @tech{style properties} are currently recognized:
 
 @itemize[
 
  @item{@racket[attributes] structure --- Provides additional HTML
        attributes for the @tt{<ul>} or @tt{<ol>} tag.}
 
  @item{@indexed-racket['never-indents] --- For Latex and @tech{compound
        paragraphs}; see @racket[compound-paragraph].}
 
 ]}
 
 
 @defstruct[nested-flow ([style style?]
                         [blocks (listof block?)])]{
 
 A @techlink{nested flow} has a style and a @tech{flow}.
 
 In @racket[style], the @tech{style name} is normally a string that
 corresponds to a CSS class for HTML @tt{<blockquote>} output or a Latex
 environment (see @secref["extra-style"]). The following symbolic style
 names are recognized:
 
 @itemize[
 
  @item{@indexed-racket['inset] --- Insets the nested flow relative to
        surrounding text.}
 
  @item{@indexed-racket['code-inset] --- Insets the nested flow relative to
        surrounding text in a way suitable for code. If the nested flow
        has a single block, then it is @tech{boxable} in the sense of
        @racket[box-mode] for Latex output.}
 
  @item{@indexed-racket['vertical-inset] --- Insets the nested flow vertically
        relative to surrounding text, but not horizontally. If the
        nested flow has a single block, then it is @tech{boxable} in the sense
        of @racket[box-mode] for Latex output.}
 
 ]
 
 The following @tech{style properties} are currently recognized:
 
 @itemize[
 
  @item{@indexed-racket['command] --- For Latex output, a string @tech{style
        name} is used as a command name instead of an environment
        name.}
 
  @item{@indexed-racket['multicommand] --- For Latex output, a string
        @tech{style name} is used as a command name with a separate
        argument for each block in @racket[blocks].}
 
  @item{@racket[attributes] structure --- Provides additional HTML
        attributes for the @tt{<blockquote>} tag.}
 
  @item{@indexed-racket['never-indents] --- For Latex and @tech{compound
        paragraphs}; see @racket[compound-paragraph].}
 
  @item{@racket[box-mode] structure --- For Latex output, uses an alternate
        rendering form for @tech{boxing contexts} (such as a table cell); see
        @racket[box-mode].}
 
  @item{@indexed-racket['decorative] --- The content of the nested flow is intended
        for decoration. Text output skips a decorative nested flow.}
 
  @item{@racket[alt-tag] structure --- Generates the indicated HTML tag
        instead of @tt{<blockquote>}.}
 
  @item{@indexed-racket['pretitle] --- For Latex, raises the contents
    of the flow to above the title.}
 ]}
 
 
 @defstruct[compound-paragraph ([style style?]
                                [blocks (listof block?)])]{
 
 A @techlink{compound paragraph} has a @tech{style} and a list of
 @tech{blocks}.
 
 For HTML, a @racket[paragraph] block in @racket[blocks] is rendered
 without a @tt{<p>} tag, unless the paragraph has a style with a
 non-@racket[#f] @tech{style name}. For Latex, each @tech{block} in
 @racket[blocks] is rendered with a preceding @ltx{noindent}, unless
 the block has the @racket['never-indents] property (checking
 recursively in a @racket[nested-flow] or @racket[compound-paragraph]
 if the @racket[nested-flow] or @racket[compound-paragraph] itself has
 no @racket['never-indents] property).
 
 The @racket[style] field of a compound paragraph is normally a string
 that corresponds to a CSS class for HTML output or Latex environment
 for Latex output (see @secref["extra-style"]). The following
 @tech{style properties} are currently recognized:
 
 @itemize[
 
  @item{@indexed-racket['command] --- For Latex output, a string @tech{style
        name} is used as a command name instead of an environment
        name.}
 
  @item{@racket[alt-tag] structure --- Generates the given HTML tag
        instead of @tt{<p>}.}
 
  @item{@racket[attributes] structure --- Provides additional HTML
        attributes for the @tt{<p>} or alternate tag.}
 
  @item{@indexed-racket['never-indents] --- For Latex within another
        @tech{compound paragraph}; see above.}
 
 ]}
 
 
 @defstruct[traverse-block ([traverse block-traverse-procedure/c])]{
 
 Produces another block during the @tech{traverse pass}, eventually.
 
 The @racket[traverse] procedure is called with @racket[_get] and
 @racket[_set] procedures to get and set symbol-keyed information; the
 @racket[traverse] procedure should return either a @tech{block} (which
 effectively takes the @racket[traverse-block]'s place) or a procedure
 like @racket[traverse] to be called in the next iteration of the
 @tech{traverse pass}.
 
 All @racket[traverse-element] and @racket[traverse-block]s that have
 not been replaced are forced in document order relative to each other
 during an iteration of the @tech{traverse pass}.
 
 The @racket[_get] procedure passed to @racket[traverse] takes a symbol
 and any value to act as a default; it returns information registered
 for the symbol or the given default if no value has been
 registered. The @racket[_set] procedure passed to @racket[traverse]
 takes a symbol and a value to be registered for the symbol.
 
 @margin-note*{See also @racket[cond-block] in @racketmodname[scriblib/render-cond].}
 @;
 The symbol @indexed-racket['scribble:current-render-mode] is
 automatically registered to a list of symbols that describe the
 target of document rendering. The list contains @racket['html]
 when rendering to HTML, @racket['latex] when rendering via Latex, and
 @racket['text] when rendering to text. The registration of
 @racket['scribble:current-render-mode] cannot be changed via
 @racket[_set].}
 
 
 @defstruct[delayed-block ([resolve (any/c part? resolve-info? . -> . block?)])]{
 
 The @racket[resolve] procedure is called during the @techlink{resolve
 pass} to obtain a normal @tech{block}. The first argument to
 @racket[resolve] is the renderer.
 
 }
 
 
 @defstruct[element ([style element-style?]
                     [content content?])]{
 
 Styled @tech{content} within an enclosing @tech{paragraph} or other content.
 
 The @racket[style] field can be a @racket[style] structure, but it can
 also be just a @tech{style name}.
 
 In @racket[style], a string @tech{style name} corresponds to a CSS
 class for HTML output and a macro name for Latex output (see
 @secref["extra-style"]). The following symbolic style names are
 recognized:
 
 @itemize[
 
  @item{@indexed-racket['tt], @racket['italic], @racket['bold], @racket['roman], @racket['sf],
        @racket['url], @racket['subscript], @racket['superscript], 
        @racket['smaller], @racket['larger] ---
        Basic styles recognized by all renders.}
 
  @item{@indexed-racket['hspace] --- Renders its @racket[content] as monospace
        blanks.}
  
  @item{@indexed-racket['newline] --- Renders a line break independent of
        the @racket[content].}
 
  @item{@indexed-racket['no-break] --- Prevents line breaks when rendering
        @racket[content].}
 
 ]
 
 The following @tech{style properties} are currently recognized:
 
 @itemize[
 
  @item{@racket[target-url] structure --- Generates a hyperlink.}
 
  @item{@racket[url-anchor] structure --- For HTML, inserts a hyperlink
        target before @racket[content].}
 
  @item{@racket[color-property] structure --- Applies a color to the
        text of @racket[content].}
 
  @item{@racket[background-color-property] structure --- Applies a
        color to the background of @racket[content].}
 
  @item{@racket[alt-tag] structure --- Generates the given HTML tag
        instead of the default one (@tt{<span>}, @tt{<b>}, @|etc|).}
 
  @item{@racket[attributes] structure --- Provides additional HTML
        attributes for a tag.}
 
  @item{@racket[hover-property] structure --- For HTML, adds a text
        label to the content to be shown when the mouse hovers over
        it.}
 
  @item{@racket[script-property] structure --- For HTML, supplies a
        script alternative to @racket[content].}
 
  @item{@racket[xexpr-property] structure --- For HTML, supplies literal
        HTML to render before and after @racket[content].}
 
   @item{@indexed-racket['aux] --- Intended for use in titles, where the
         auxiliary part of the title can be omitted in hyperlinks. See,
         for example, @racket[secref].}
 
   @item{@indexed-racket['tt-chars] --- For Latex output, when the @tech{style
         name} is a string, render the element's content with escapes
         suitable for Latex @tt{tt} mode.}
 
   @item{@indexed-racket['exact-chars] --- For Latex output, when the @tech{style
         name} is a string or @racket[#f], render the elements content exactly
         (without escapes).}
 
   @item{@racket[command-extras] structure --- For Latex output,
          adds strings as arguments to the Latex command.}
 
 ]
 
 @history[#:changed "1.6" @elem{Changed @racket['exact-chars] handling to
          take effect when the style name is @racket[#f].}
          #:changed "1.27" @elem{Changed to support @racket[xexpr-property].}]}
 
 
 @defstruct[(image-element element) ([path (or/c path-string?
                                                 (cons/c 'collects (listof bytes?)))]
                                     [suffixes (listof #rx"^[.]")]
                                     [scale real?])]{
 
 Used as a style for an @racket[element] to inline an image. The
 @racket[path] field can be a result of
 @racket[path->main-collects-relative].
 
 For each string in @racket[suffixes], if the rendered works with the
 corresponding suffix, the suffix is added to @racket[path] and used if
 the resulting path refers to a file that exists. The order in
 @racket[suffixes] determines the order in which suffixes are
 tried. The HTML renderer supports @racket[".png"], @racket[".gif"], and @racket[".svg"],
 while the Latex renderer supports @racket[".png"], @racket[".pdf"],
 and @racket[".ps"] (but rendering Latex output to PDF will not work
 with @racket[".ps"] files, while rendering to Latex DVI output works
 only with @racket[".ps"] files). If @racket[suffixes] is empty or if
 none of the suffixes lead to files that exist, @racket[path] is used
 as-is.
 
 The @racket[scale] field scales the image in its rendered form.}
 
 
 @defstruct[(target-element element) ([_tag tag?])]{
 
 Declares the content as a hyperlink target for @racket[_tag].}
 
 
 @defstruct[(toc-target-element target-element) ()]{
 
 Like @racket[target-element], the content is also a kind of section
 label to be shown in the ``on this page'' table for HTML output.}
 
 
 @defstruct[(toc-target2-element toc-target-element) ([toc-content content?])]{
 
 Extends @racket[target-element] with a separate field for the content
 to be shown in the ``on this page'' table for HTML output.}
 
 
 @defstruct[(page-target-element target-element) ()]{
 
 Like @racket[target-element], but a link to the element goes to the
 top of the containing page.}
 
 
 @defstruct[(redirect-target-element target-element) ([alt-path path-string?]
                                                      [alt-anchor string?])]{
 
 Like @racket[target-element], but a link to the element is redirected
 to the given URL.}
 
 
 @defstruct[(toc-element element) ([toc-content content?])]{
 
 Similar to @racket[toc-target-element], but with specific content for
 the ``on this page'' table specified in the @racket[toc-content]
 field.}
 
 
 @defstruct[(link-element element) ([tag tag?])]{
 
 Represents a hyperlink to @racket[_tag].
 
 Normally, the content of the element is rendered as the hyperlink.
 When @racket[_tag] is a part tag and the content of the element is
 @racket[null], however, rendering is treated specially based on the
 @racket[_mode] value of a @racket[link-render-style] @tech{style
 property}:
 
 @itemlist[
 
  @item{For HTML output, in the @racket['default] mode, the generated
        reference is the hyperlinked title of the elements in the
        section's title content, except that elements with the
        @racket['aux] @tech{style property} are omitted in the
        hyperlink label.
 
        In @racket['number] mode, the section title is not shown.
        Instead, the word ``section'' is shown followed by a
        hyperlinked section number. The word ``section'' starts in
        uppercase if the element's style includes a @racket['uppercase]
        property.}
 
  @item{For Latex/PDF output, the generated reference's format can
        depend on the document style in addition the @racket[_mode].
        For the @racket['default] mode and a default document style, a
        section number is shown by the word ``section'' followed by the
        section number, and the word ``section'' and the section number
        are together hyperlinked. The word ``section'' starts in
        uppercase if the element's style includes a @racket['uppercase]
        property. The @racketmodname[scribble/manual] style uses the
        symbol ``§'' in place of the word ``section''.
 
        In @racket['number] mode, rendering is the same, except that
        only the number is hyperlinked, not the word ``section'' or
        the ``§'' symbol.
 
        A new document style can customize Latex/PDF output (see
        @secref["config"]) by redefining the @ltx{SecRefLocal}, @|etc|,
        macros (see @secref["builtin-latex"]). The @ltx{SecRef},
        @|etc|, variants are used in @racket['number] mode.}
 
 ]
 
 If a @racket[link-render-style] @tech{style property} is not attached
 to a @racket[link-element] that refers to a part, a
 @racket[link-render-style] @tech{style property} that is attached to
 an enclosing part is used, since attaching a
 @racket[link-render-style] @tech{style property} to a part causes
 @racket[current-link-render-style] to be set while rendering the part.
 Otherwise, the render-time value of @racket[current-link-render-style]
 determine's a @racket[link-element]'s rendering.
 
 The following style properties are recognized in addition to the style
 properties for all @racket[element]s:
 
 @itemize[
 
  @item{@racket[link-render-style] structure --- As described above.}
 
  @item{@indexed-racket['indirect-link] --- For HTML output, treats the link as
        ``external''. When rendering to HTML and the
        @method[render-mixin set-external-tag-path] method is called to
        provide an external-link URL, then the resolution of the
        hyperlink can be deferred until the link is clicked (or, in
        some cases, patched by JavaScript when the documentation is
        viewed in a browser).}
 
 ]
 
 @history[#:changed "1.26" @elem{Added @racket[link-render-style] support.}]}
 
 
 @defstruct[(index-element element) ([tag tag?]
                                     [plain-seq (and/c pair? (listof string?))]
                                     [entry-seq (listof content?)]
                                     [desc any/c])]{
 
 The @racket[plain-seq] specifies the keys for sorting, where the first
 string is the main key, the second is a sub-key, etc. For
 example, an ``night'' portion of an index might have sub-entries for
 ``night, things that go bump in'' and ``night, defender of the''. The
 former would be represented by @racket[plain-seq] @racket['("night"
 "things that go bump in")], and the latter by @racket['("night"
 "defender of the")]. Naturally, single-string
 @racket[plain-seq] lists are the common case, and at least one word is
 required, but there is no limit to the word-list length. The strings in 
 @racket[plain-seq] must not contain a newline character.
 
 The @racket[entry-seq] list must have the same length as
 @racket[plain-seq]. It provides the form of each key to render in the
 final document.
 
 The @racket[desc] field provides additional information about the
 index entry as supplied by the entry creator. For example, a reference
 to a procedure binding can be recognized when @racket[desc] is an
 instance of @racket[procedure-index-desc]. See
 @racketmodname[scribble/manual-struct] for other typical types of
 @racket[desc] values.
 
 See also @racket[index].}
 
 
 @defstruct[multiarg-element ([style element-style?]
                              [contents (listof content?)])]{
 
 Like @racket[element] with a list for content, except that for Latex
 output, if the @tech{style name} in @racket[style] is a string, then
 it corresponds to a Latex command that accepts as many arguments (each
 in curly braces) as elements of @racket[contents].}
 
 
 @defstruct[traverse-element ([traverse element-traverse-procedure/c])]{
 
 @margin-note*{See also @racket[cond-element] in @racketmodname[scriblib/render-cond].}
 @;
 Like @racket[traverse-block], but the @racket[traverse] procedure must
 eventually produce @tech{content}, rather than a @tech{block}.}
 
 
 @defstruct[delayed-element ([resolve (any/c part? resolve-info? . -> . content?)]
                             [sizer (-> any/c)]
                             [plain (-> any/c)])]{
 
 The @racket[render] procedure's arguments are the same as for
 @racket[delayed-block], but the result is @techlink{content}. 
 Unlike @racket[delayed-block], the
 result of the @racket[render] procedure's argument is remembered on
 the first call for re-use for a particular resolve pass.
 
 The @racket[sizer] field is a procedure that produces a substitute
 @techlink{content} for the delayed element for the purposes of
 determining the delayed element's width (see @racket[element-width]).
 
 The @racket[plain] field is a procedure that produces a substitute
 @techlink{content} when needed before the @techlink{collect pass},
 such as when @racket[element->string] is used before the @tech{collect
 pass}.}
 
 
 @defstruct[part-relative-element ([resolve (collect-info? . -> . content?)]
                                   [sizer (-> any/c)]
                                   [plain (-> any/c)])]{
 
 Similar to @racket[delayed-block], but the replacement
 @techlink{content} is obtained in the @techlink{collect pass} by
 calling the function in the @racket[resolve] field.
 
 The @racket[resolve] function can call @racket[collect-info-parents]
 to obtain a list of @techlink{parts} that enclose the element,
 starting with the nearest enclosing section. Functions like
 @racket[part-collected-info] and @racket[collected-info-number] can
 extract information like the part number.}
 
 
 @defstruct[(collect-element element) ([collect (collect-info . -> . any)])]{
 
 Like @racket[element], but the @racket[collect] procedure is called
 during the @techlink{collect pass}. The @racket[collect] procedure
 normally calls @racket[collect-put!].
 
 Unlike @racket[delayed-element] or @racket[part-relative-element], the
 element remains intact (i.e., it is not replaced) by either the
 @tech{collect pass} or @tech{resolve pass}.}
 
 
 @defstruct[(render-element element) ([render (any/c part? resolve-info? . -> . any)])]{
 
 Like @racket[delayed-element], but the @racket[render] procedure is called
 during the @techlink{render pass}.
 
 If a @racket[render-element] instance is serialized (such as when
 saving collected info), it is reduced to a @racket[element] instance.}
 
 
 @defstruct[collected-info ([number (listof part-number-item?)]
                            [parent (or/c #f part?)]
                            [info any/c])]{
 
 Computed for each part by the @techlink{collect pass}.
 
 The length of the @racket[number] list indicates the section's nesting
 depth. Elements of @racket[number] correspond to the section's number,
 it's parent's number, and so on (that is, the section numbers are in
 reverse order):
 
 @itemlist[
 
  @item{A number value corresponds to a normally numbered
        section.}
 
  @item{A non-empty string corresponds to a @racket['grouper] section,
        which is shown as part of the combined section number only when
        it's the first element.}
 
  @item{A a list corresponds to a @tech{numberer}-generated section
        string plus its separator string, where the separator is used
        in a combined section number after the section string and
        before a subsection's number (or, for some output modes, before
        the title of the section).}
 
  @item{For an unnumbered section, a @racket[#f] is used in place of
        any number or lists element, while @racket[""] is used in place
        of all non-empty strings.}
 
 ]
 
 @history[#:changed "1.1" @elem{Added @racket[(list/c string? string?)]
                                number items for
                                @tech{numberer}-generated section
                                numbers.}]}
 
 
 @defstruct[target-url ([addr path-string?])]{
 
 Used as a @tech{style property} for an @racket[element]. A path is
 allowed for @racket[addr], but a string is interpreted as a URL rather
 than a file path.}
 
 
 @defstruct[document-version ([text (or/c string? #f)])]{
 
 Used as a @tech{style property} for a @racket[part] to indicate a
 version number.}
 
 
 @defstruct[document-date ([text (or/c string? #f)])]{
 
 Used as a @tech{style property} for a @racket[part] to indicate a
 date (which is typically used for Latex output).}
 
 
 @defstruct[color-property ([color (or/c string? (list/c byte? byte? byte?))])]{
 
 Used as a @tech{style property} for an @racket[element] to set its
 color. Recognized string names for @racket[color] depend on the
 renderer, but at the recognized set includes at least
 @racket["white"], @racket["black"], @racket["red"], @racket["green"],
 @racket["blue"], @racket["cyan"], @racket["magenta"], and
 @racket["yellow"]. When @racket[color] is a list of bytes, the values
 are used as RGB levels.
 
 When rendering to HTML, a @racket[color-property] is also recognized
 for a @tech{block}, @racket[part] (and used for the title in the
 latter case)or cell in a @racket[table].}
 
 
 @defstruct[background-color-property ([color (or/c string? (list/c byte? byte? byte?))])]{
 
 Like @racket[color-property], but sets the background color.}
 
 
 @defstruct[table-cells ([styless (listof (listof style?))])]{
 
 Used as a @tech{style property} for a @racket[table] to set its cells'
 styles.
 
 If a cell style has a string name, it is used as an HTML class for the
 @tt{<td>} tag or as a Latex command name.
 
 The following are recognized as cell-@tech{style properties}:
 
 @itemize[
 
  @item{@indexed-racket['left] --- Left-align the cell content.}
 
  @item{@indexed-racket['right] --- Right-align the cell content top baselines.}
 
  @item{@indexed-racket['center] --- Center the cell content horizontally.}
 
  @item{@indexed-racket['top] --- Top-align the cell content.}
 
  @item{@indexed-racket['baseline] --- Align the cell content top baselines.}
 
  @item{@indexed-racket['bottom] --- bottom-align the cell content.}
 
  @item{@indexed-racket['vcenter] --- Center the cell content vertically.}
 
  @item{@indexed-racket['border] --- Draw a line around all sides of the
        cell. Borders along a shared edge of adjacent cells are
        collapsed into a single line.}
 
  @item{@indexed-racket['left-border], @indexed-racket['right-border],
        @indexed-racket['top-border], or @indexed-racket['bottom-border] --- Draw a
        line along the corresponding side of the cell (with the same
        border collapsing as for @racket['border]).}
 
  @item{@racket[color-property] structure --- For HTML, applies a color
        to the cell content.}
 
  @item{@racket[background-color-property] structure --- For HTML,
        applies a color to the background of the cell.}
 
  @item{@racket[attributes] --- Provides additional HTML attributes
        for the cell's @tt{<td>} tag.}
 
 ]
 
 @history[#:changed "1.1" @elem{Added @racket[color-property] and 
                                @racket[background-color-property] support.}
          #:changed "1.4" @elem{Added @racket['border], @racket['left-border],
                                @racket['right-border], @racket['top-border],
                                and @racket['bottom-border] support.}]}
 
 
 @defstruct[table-columns ([styles (listof style?)])]{
 
 Like @racket[table-cells], but with support for a
 @racket[column-attributes] property in each style, and the
 @racket[styles] list is otherwise duplicated for each row in the
 table. The non-@racket[column-attributes] parts of a
 @racket[table-columns] are used only when a @racket[table-cells] property is
 not present along with the @racket[table-columns] property.
 
 For HTML table rendering, for each column that has a
 @racket[column-attributes] property in the corresponding element of
 @racket[styles], the attributes are put into an HTML @tt{col} tag
 within the table.}
 
 
 @deftogether[(
 @defstruct[box-mode ([top-name string?]
                      [center-name string?]
                      [bottom-name string?])]
 @defproc[(box-mode* [name string?]) box-mode?]
 )]{
 
 As a @tech{style property}, indicates that a @tech{nested flow} or
 @tech{paragraph} is @deftech{boxable} when it is used in a
 @deftech{boxing context} for Latex output, but a @tech{nested flow} is
 @tech{boxable} only if its content is also @tech{boxable}.
 
 A @tech{boxing context} starts with a table cell in a multi-column
 table, and the content of a @tech{block} in a @tech{boxing context} is
 also in a @tech{boxing context}. If the cell's content is
 @tech{boxable}, then the content determines the width of the cell,
 otherwise a width is imposed. A @tech{paragraph} with a @racket[#f]
 @tech{style name} is @tech{boxable} as a single line; the
 @racket['wraps] @tech{style name} makes the paragraph
 non-@tech{boxable} so that its width is imposed and its content can
 use multiple lines. A @tech{table} is @tech{boxable} when that all of
 its cell content is boxable.
 
 To generate output in box mode, the @racket[box-mode] property
 supplies Latex macro names to apply to the @tech{nested flow} or
 @tech{paragraph} content. The @racket[top-name] macro is used if the
 box's top line is to be aligned with other boxes, @racket[center-name]
 if the box's center is to be aligned, and @racket[bottom-name] if the
 box's bottom line is to be aligned. The @racket[box-mode*] function
 creates a @racket[box-mode] structure with the same name for all three
 fields.
 
 A @racket[box-mode] @tech{style property} overrides any automatic
 boxed rendering (e.g., for a @tech{paragraph} with @tech{style name}
 @racket[#f]).  If a @tech{block} has both a @racket[box-mode]
 @tech{style property} and a @racket['multicommand] @tech{style
 property}, then the Latex macro @racket[top-name],
 @racket[center-name], or @racket[bottom-name] is applied with a
 separate argument for each of its content.}
 
 
 @defproc[(block? [v any/c]) boolean?]{
 
 Returns @racket[#t] if @racket[v] is a @racket[paragraph],
 @racket[table], @racket[itemization], @racket[nested-flow],
 @racket[traverse-block], or @racket[delayed-block], @racket[#f]
 otherwise.}
 
 
 @defproc[(content? [v any/c]) boolean?]{
 
 Returns @racket[#t] if @racket[v] is a string, symbol,
 @racket[element], @racket[multiarg-element],
 @racket[traverse-element], @racket[delayed-element],
 @racket[part-relative-element], a convertible value in 
 the sense of @racket[convertible?], or list of @tech{content}. 
 Otherwise, it returns @racket[#f].}
 
 
 @defstruct[style ([name (or/c string? symbol? #f)]
                   [properties list?])]{
 
 Represents a @techlink{style}.}
 
 
 @defthing[plain style?]{
 
 A style @racket[(make-style #f null)].}
 
 
 @defproc[(element-style? [v any/c]) boolean?]{
 
 Returns @racket[#t] if @racket[v] is a string, symbol, @racket[#f],
 or @racket[style] structure.}
 
 
 @defproc[(tag? [v any/c]) boolean?]{
 
 Returns @racket[#t] if @racket[v] is acceptable as a link
 @techlink{tag}, which is a list containing a symbol and either a
 string, a @racket[generated-tag] instance, or a non-empty list
 of @racket[serializable?] values.}
 
 
 @defstruct[generated-tag ()]{
 
 A placeholder for a tag to be generated during the @techlink{collect
  pass}. Use @racket[tag-key] to convert a tag containing a
  @racket[generated-tag] instance to one containing a string.
 
 }
 
 
 @defproc*[([(content->string (content content?)) string?]
            [(content->string (content content?) (renderer any/c) (p part?) (info resolve-info?)) string?])]{
 
 Converts @tech{content} to a single string (essentially
 rendering the content as ``plain text'').
 
 If @racket[p] and @racket[info] arguments are not supplied, then a
 pre-``collect'' substitute is obtained for @tech{delayed
 elements}. Otherwise, the two arguments are used to force the
 @tech{delayed element} (if it has not been forced already).}
 
 @defproc[(content-width [c content?]) exact-nonnegative-integer?]{
 
 Returns the width in characters of the given @tech{content}.
 
 }
 
 
 @defproc[(block-width (e block?)) exact-nonnegative-integer?]{
 
 Returns the width in characters of the given @tech{block}.}
 
 
 @defproc[(part-number-item? [v any/c]) boolean]{
 
 Return @racket[#t] if @racket[v] is @racket[#f], an exact non-negative
 integer, a string, or a list containing two strings. See @racket[collected-info]
 for information on how different representations are used for numbering.
 
 @history[#:added "1.1"]}
 
 
 @deftogether[(
 @defproc[(numberer? [v any/c]) boolean?]
 @defproc[(make-numberer [step (any/c (listof part-number-item?)
                                . -> .
                                (values part-number-item? any/c))]
                         [initial-value any/c])
           numberer?]
 @defproc[(numberer-step [n numberer?]
                         [parent-number (listof part-number-item?)]
                         [ci collect-info?]
                         [numberer-values hash?])
          (values part-number-item? hash?)]
 )]{
 
 A @deftech{numberer} implements a representation of a section number
 that increment separately from the default numbering style and that
 can be rendered differently than as Arabic numerals.
 
 The @racket[numberer?] function returns @racket[#t] if @racket[v] is a
 @tech{numberer}, or @racket[#f] otherwise.
 
 The @racket[make-numberer] function creates a @tech{numberer}. The
 @racket[step] function computes both the current number's
 representation and increments the number, where the ``number'' can be
 an arbitrary value; the @racket[initial-value] argument determines the
 initial value of the ``number'', and the @racket[step] function
 receives the current value as its first argument and returns an
 incremented value as its second result. A numberer's ``number'' value
 starts fresh at each new nesting level. In addition to the numberer's
 current value, the @racket[step] function receives the parent
 section's numbering (so that its result can depend on the part's
 nesting depth).
 
 The @racket[numberer-step] function is normally used by a renderer. It
 applies a @tech{numberer}, given the parent section's number, a
 @racket[collect-info] value, and a hash table that accumulates
 @tech{numberer} values at a given nesting layer. The
 @racket[collect-info] argument is needed because a @tech{numberer}'s
 identity is based on a @racket[generated-tag]. The result of
 @racket[numberer-step] is the rendered form of the current section
 number plus an updated hash table with an incremented value for the
 @tech{numberer}.
 
 Typically, the rendered form of a section number (produced by
 @racket[numberer-step]) is a list containing two strings. The first
 string is the part's immediate number, which can be combined with a
 prefix for enclosing parts' numbers. The second string is a separator
 that is placed after the part's number and before a subsection's
 number for each subsection. If @racket[numberer-step] produces a plain
 string for the rendered number, then it is not added as a prefix to
 subsection numbers. See also @racket[collected-info].
 
 @history[#:added "1.1"]}
 
 
 @defstruct[link-render-style ([mode (or/c 'default 'number)])]{
 
 Used as a @tech{style property} for a @racket[part] or a specific
 @racket[link-element] to control the way that a hyperlink is rendered
 for a part via @racket[secref] or for a figure via @racket[figure-ref]
 from @racketmodname[scriblib/figure].
 
 The @racket['default] and @racket['number] modes represent generic
 hyperlink-style configurations that could make sense for various kinds
 of references. The @racket['number] style is intended to mean that a
 specific number is shown for the reference and that only the number is
 hyperlinked. The @racket['default] style is more flexible, allowing a
 more appropriate choice for the rendering context, such as using the
 target section's name for a hyperlink in HTML.
 
 @history[#:added "1.26"]}
 
 
 @defparam[current-link-render-style style link-render-style?]{
 
 A parameter that determines the default rendering style for a section
 link.
 
 When a @racket[part] has a @racket[link-render-style] as one of its
 @tech{style properties}, then the @racket[current-link-render-style]
 parameter is set during the @tech{resolve pass} and @tech{render pass}
 for the @racket[part]'s content.
 
 @history[#:added "1.26"]}
 
 
 @defstruct[collect-info ([fp any/c] [ht any/c] [ext-ht any/c] 
                          [ext-demand (tag? collect-info? . -> . any/c)]
                          [parts any/c] 
                          [tags any/c] [gen-prefix any/c] 
                          [relatives any/c] 
                          [parents (listof part?)])]{
 
 Encapsulates information accumulated (or being accumulated) from the
 @techlink{collect pass}. The fields are exposed, but not currently
 intended for external use, except that @racket[collect-info-parents]
 is intended for external use.
 
 }
 
 @defstruct[resolve-info ([ci any/c] [delays any/c] [undef any/c] [searches any/c])]{
 
 Encapsulates information accumulated (or being accumulated) from the
 @techlink{resolve pass}. The fields are exposed, but not currently
 intended for external use.
 
 }
 
 @defproc[(info-key? [v any/c]) boolean?]{
 
 Returns @racket[#t] if @racket[v] is an @deftech{info key}: a list of
 at least two elements whose first element is a symbol. The result is
 @racket[#f] otherwise.
 
 For a list that is an info tag, the interpretation of the second
 element of the list is effectively determined by the leading symbol,
 which classifies the key. However, a @racket[#f] value as the second
 element has an extra meaning: collected information mapped by such
 info keys is not propagated out of the part where it is collected;
 that is, the information is available within the part and its
 sub-parts, but not in ancestor or sibling parts.
 
 Note that every @techlink{tag} is an info key.
 
 }
 
 @defproc[(collect-put! [ci collect-info?] [key info-key?] [val any/c])
          void?]{
 
 Registers information in @racket[ci]. This procedure should be called
 only during the @techlink{collect pass}.
 
 }
 
 @defproc[(resolve-get [p (or/c part? #f)] [ri resolve-info?] [key info-key?])
          any/c]{
 
 Extract information during the @techlink{resolve pass} or
 @techlink{render pass} for @racket[p] from @racket[ri], where the
 information was previously registered during the @techlink{collect
 pass}. See also @secref["passes"].
 
 The result is @racket[#f] if the no value for the given key is found.
 Furthermore, the search failure is recorded for potential consistency
 reporting, such as when @exec{racket setup} is used to build
 documentation.
 
 }
 
 
 @defproc[(resolve-get/ext? [p (or/c part? #f)] [ri resolve-info?] [key info-key?])
          (values any/c boolean?)]{
 
 Like @racket[resolve-get], but returns a second value to indicate
 whether the resulting information originated from an external source
 (i.e., a different document).}
 
 
 @defproc[(resolve-get/ext-id [p (or/c part? #f)] [ri resolve-info?] [key info-key?])
          (values any/c (or/c boolean? string?))]{
 
 Like @racket[resolve-get/ext?], but the second result can be a string
 to indicate the source document's identification as established via
 @racket[load-xref] and a @racket[#:doc-id] argument.
 
 @history[#:added "1.1"]}
 
 
 @defproc[(resolve-search [dep-key any/c] [p (or/c part? #f)] [ri resolve-info?] [key info-key?])
          void?]{
 
 Like @racket[resolve-get], but a shared @racket[dep-key] groups
 multiple searches as a single request for the purposes of consistency
 reporting and dependency tracking. That is, a single success for the
 same @racket[dep-key] means that all of the failed attempts for the
 same @racket[dep-key] have been satisfied. However, for dependency
 checking, such as when using @exec{racket setup} to re-build
 documentation, all attempts are recorded (in case external changes
 mean that an earlier attempt would succeed next time).
 
 }
 
 @defproc[(resolve-get/tentative [p (or/c part? #f)] [ri resolve-info?] [key info-key?])
          any/c]{
 
 Like @racket[resolve-search], but without dependency tracking. For
 multi-document settings where dependencies are normally tracked, such
 as when using @exec{racket setup} to build documentation, this function
 is suitable for use only for information within a single document.
 
 }
 
 @defproc[(resolve-get-keys [p (or/c part? #f)]
                            [ri resolve-info?] 
                            [pred (info-key? . -> . any/c)])
          list?]{
 
 Applies @racket[pred] to each key mapped for @racket[p] in
 @racket[ri], returning a list of all keys for which @racket[pred]
 returns a true value.
 
 }
 
 @defproc[(part-collected-info [p part?]
                               [ri resolve-info?])
          collected-info?]{
 
 Returns the information collected for @racket[p] as recorded within
 @racket[ri].
 
 }
 
 @defproc[(tag-key [t tag?] [ri resolve-info?]) tag?]{
 
 Converts a @racket[generated-tag] value with @racket[t] to a string.
 
 }
 
 
 @defproc[(traverse-block-block [b traverse-block?]
                                [i (or/c resolve-info? collect-info?)])
          block?]{
 
 Produces the block that replaces @racket[b].}
 
 
 @defproc[(traverse-element-content [e traverse-element?]
                                    [i (or/c resolve-info? collect-info?)])
          content?]{
 
 Produces the content that replaces @racket[e].}
 
 
 @defthing[block-traverse-procedure/c contract?]{
 
 Defined as
 
 @racketblock[
   (recursive-contract
    ((symbol? any/c . -> . any/c)
     (symbol? any/c . -> . any)
     . -> . (or/c block-traverse-procedure/c
                  block?)))
 ]}
 
 @defthing[element-traverse-procedure/c contract?]{
 
 Defined as
 
 @racketblock[
   (recursive-contract
    ((symbol? any/c . -> . any/c)
     (symbol? any/c . -> . any)
     . -> . (or/c element-traverse-procedure/c
                  content?)))
 ]}
 
 @; ----------------------------------------
 
 @section{HTML Style Properties}
 
 @defmodule[scribble/html-properties]{ The
 @racket[scribble/html-properties] library provides datatypes used as
 @tech{style properties} for HTML rendering.}
 
 
 @defstruct[attributes ([assoc (listof (cons/c symbol? string?))])]{
 
 Used as a @tech{style property} to add arbitrary attributes to an HTML
 tag.}
 
 
 @defstruct[alt-tag ([name (and/c string? #rx"^[a-zA-Z0-9]+$")])]{
 
 Use as a @tech{style property} for an @racket[element],
 @racket[paragraph], or @racket[compound-paragraph] to substitute an
 alternate HTML tag (instead of @tt{<span>}, @tt{<p>}, @tt{<div>},
 @|etc|).}
 
 
 @defstruct[column-attributes ([assoc (listof (cons/c symbol? string?))])]{
 
 Used as a @tech{style property} on a style with @racket[table-columns]
 to add arbitrary attributes to an HTML @tt{col} tag within the table.}
 
 
 @defstruct[url-anchor ([name string?])]{
 
 Used as a @tech{style property} with @racket[element] to insert an
 anchor before the element.}
 
 
 @defstruct[hover-property ([text string?])]{
 
 Used as a @tech{style property} with @racket[element] to add text that
 is shown when the mouse hovers over the element.}
 
 
 @defstruct[script-property ([type string?]
                            [script (or/c path-string? (listof string?))])]{
 
 Used as a @tech{style property} with @racket[element] to supply a
 script alternative to the element content.}
 
 
 @defstruct[xexpr-property ([before xexpr/c]
                            [after xexpr/c])]{
 
 Used as a @tech{style property} with @racket[element] to supply literal
 HTML that is rendered before and after element content.
 
 @as-examples["Example:"
 @codeblock[#:keep-lang-line? #t]|{
   #lang scribble/base
   @(require scribble/core
             scribble/html-properties
             (only-in xml cdata))
 
   @(define comments (xexpr-property
                      (cdata #f #f "<!-- before -->")
                      (cdata #f #f "<!-- after -->")))
 
   Here is some
   @elem[#:style (style #f (list comments))]{content with comments around}.
 }|]
 
 @history[#:added "1.27"]}
 
 
 @defstruct[css-addition ([path (or/c path-string? 
                                      (cons/c 'collects (listof bytes?))
                                      url?
                                      bytes?)])]{
 
 Used as a @tech{style property} to supply a CSS file (if @racket[path]
 is a path, string, or list), URL (if @racket[path] is a @racket[url])
 or content (if @racket[path] is a byte string) to be referenced or
 included in the generated HTML. This property can be attached to any
 style, and all additions are collected and lifted to the enclosing
 generated HTML. When the style property is attached to a @tech{part},
 then it is also propagated to any generated HTML for a subpart of the
 part.
 
 The @racket[path] field can be a result of
 @racket[path->main-collects-relative].}
 
 @defstruct[css-style-addition ([path (or/c path-string? 
                                            (cons/c 'collects (listof bytes?))
                                            url?
                                            bytes?)])]{
 
 Like @racket[css-addition], but added after any style files that are
 specified by a document and before any style files that are provided
 externally.}
 
 
 @defstruct[js-addition ([path (or/c path-string? 
                                     (cons/c 'collects (listof bytes?))
                                     url?
                                     bytes?)])]{
 
 Like @racket[css-addition], but for a JavaScript file instead of a CSS file.}
 
 
 @defstruct[js-style-addition ([path (or/c path-string? 
                                           (cons/c 'collects (listof bytes?))
                                           url?
                                           bytes?)])]{
 
 Like @racket[css-style-addition], but for a JavaScript file instead of a CSS file.}
 
 
 @defstruct[body-id ([value string?])]{
 
 Used as a @tech{style property} to associate an @tt{id} attribute with
 an HTML tag within a main @racket[part].}
 
 
 @defstruct[document-source ([module-path module-path?])]{
 
 Used as a @tech{style property} to associate a module path with a
 part.  Clicking on a section title within the part may show
 @racket[module-path] with the part's tag string, so that authors of
 other documents can link to the section.
 
 More specifically, the section title is given the HTML attributes
 @tt{x-source-module} and @tt{x-part-tag}, plus @tt{x-part-prefixes}
 if the section or enclosing sections declare tag prefixes, and
 @tt{x-source-pkg} if the source is found within a package at document-build time. The
 @racketmodname[scribble/manual] style recognizes those tags to make
 clicking a title show cross-reference information.
 
 @history[#:added "1.2"
          #:changed "1.7" @elem{Added @tt{x-part-prefixes}.}
          #:changed "1.9" @elem{Added @tt{x-source-pkg}.}]}
 
 
 @defstruct[html-defaults ([prefix (or/c bytes? path-string? 
                                         (cons/c 'collects (listof bytes?)))]
                           [style (or/c bytes? path-string? 
                                        (cons/c 'collects (listof bytes?)))]
                           [extra-files (listof (or/c path-string? 
                                                      (cons/c 'collects (listof bytes?))))])]{
 
 Like @racket[latex-defaults], but use for the 
 @exec{scribble} command-line tool's @DFlag{html} and
 @DFlag{htmls} modes.}
 
 
 @defstruct[head-extra ([xexpr xexpr/c])]{
 
 For a @racket[part] that corresponds to an HTML page, adds content to
 the @tt{<head>} tag.}
 
 
 @defstruct[head-addition ([xexpr xexpr/c])]{
 
 Like @racket[head-extra] in content, but propagated to enclosing and
 nested HTML pages like @racket[css-addition]. Additions to @tt{<head>}
 via @racket[head-addition] appear before additions via @racket[head-extra].
 
 @history[#:added "1.38"]}
 
 
 @defstruct[render-convertible-as ([types (listof (or/c 'png-bytes 'svg-bytes 'gif-bytes))])]{
  For a @racket[part] that corresponds to an HTML page,
  controls how objects that subscribe to the @racketmodname[file/convertible]
  protocol are rendered.
       
  The alternatives in the @racket[types] field are tried in order
  and the first one that succeeds is used in the html output.
 
  @history[#:changed "1.34" @elem{Added support for  @racket['gif-bytes].}]
 }
 
 @defstruct[part-link-redirect ([url url?])]{
 
 As a @tech{style property} on a @tech{part}, causes hyperiinks to the
 part to be redirected to @racket[url] instead of the rendered part.}
 
 @defstruct[link-resource ([path path-string?])]{
 
 As a @tech{style property} on an @racket[element], causes the elements
 to be rendered as a hyperlink to (a copy of) @racket[path].
 
 The file indicated by @racket[path] is referenced in place when
 @racket[render<%>] is instantiated with
 @racketidfont{refer-to-existing-files} as true. Otherwise, it is
 copied to the destination directory and potentially renamed to avoid
 conflicts.}
 
 
 @defstruct[install-resource ([path path-string?])]{
 
 Like @racket[link-resource], but makes @racket[path] accessible in the
 destination without rendering a hyperlink.
 
 This @tech{style property} is useful only when @racket[render<%>] is
 instantiated with @racketidfont{refer-to-existing-files} as
 @racket[#f], and only when @racket[path] does not match then name of
 any other file that is copied by the renderer to the destination.}
 
 @; ----------------------------------------
 
 @section{Latex Style Properties}
 
 @defmodule[scribble/latex-properties]{ The
 @racket[scribble/latex-properties] library provides datatypes used as
 @tech{style properties} for Latex rendering.}
 
 
 @defstruct[tex-addition ([path (or/c path-string? 
                                      (cons/c 'collects (listof bytes?))
                                      bytes?)])]{
 
 Used as a @tech{style property} to supply a @filepath{.tex} file (if
 @racket[path] is a path, string, or list) or content (if @racket[path]
 is a byte string) to be included in the generated Latex. This property
 can be attached to any style, and all additions are collected to the
 top of the generated Latex file.
 
 The @racket[path] field can be a result of
 @racket[path->main-collects-relative].}
 
 
 @defstruct[latex-defaults ([prefix (or/c bytes? path-string? 
                                          (cons/c 'collects (listof bytes?)))]
                            [style (or/c bytes? path-string? 
                                         (cons/c 'collects (listof bytes?)))]
                            [extra-files (listof (or/c path-string? 
                                                       (cons/c 'collects (listof bytes?))))])]{
 
 Used as a @tech{style property} on the main @racket[part] of a document
 to set a default prefix file, style file, and extra files (see
 @secref["config-style"]).  The defaults are used by the
 @exec{scribble} command-line tool for @DFlag{latex} or @DFlag{pdf}
 mode if none are supplied via @DFlag{prefix} and @DFlag{style} (where
 @racket[extra-files] are used only when @racket[prefix] is used). A
 byte-string value is used directly like file content, and a path can
 be a result of @racket[path->main-collects-relative].
 
 Languages (used with @hash-lang[]) like
 @racketmodname[scribble/manual] and @racketmodname[scribble/sigplan]
 add this property to a document to specify appropriate files for Latex
 rendering.
 
 See also @racketmodname[scribble/latex-prefix].}
 
 @defstruct[(latex-defaults+replacements latex-defaults)
            ([replacements (hash/c string? (or/c bytes? path-string?
                                                 (cons/c 'collects (listof bytes?))))])]{
   Like @racket[latex-defaults] but it allows for more configuration. For example if
   the @racket[replacements] maps @racket["scribble-load-replace.tex"] to @racket["my-scribble.tex"],
   then the @racket["my-scribble.tex"] file in the current directory will we used in place
   of the standard scribble package inclusion header.
 }
 
 
 @defstruct[command-extras ([arguments (listof string?)])]{
 
 Used as a @tech{style property} on an @racket[element] to add extra
 arguments to the element's command in Latex output.}
 
 @defstruct[command-optional ([arguments (listof string?)])]{
                                                   
  Used as a @tech{style property} on a @racket[element] to add
  optional arguments to the element's command in Latex output.
 
  @history[#:added "1.20"]
 }
 
 @defstruct[short-title ([text (or/c string? #f)])]{
                                                   
  Used as a @tech{style property} on a @racket[title-decl].
  Attaches a short title to the title for a @racket[part] if
  the Latex class file uses a short title.
 
  @history[#:added "1.20"]
 }
 
 @defstruct[table-row-skip ([amount string?])]{
 
  Used as a @tech{style property} in @racket[table-cells] to specify a
  spacing adjustment between the cell's row and the row afterward, such
  as @racket["1ex"] to increase the space or @racket["-1ex"] to
  decrease it. If multiple cells on a row provide this property, the
  first one in the row is used.
 
  @history[#:added "1.33"]
 }