b62bfe3bdf
The documentation for the `resolve-get` family of functions incorrectly refers to themselves as `render-get`. This commit fixes that.
1830 lines
71 KiB
Racket
1830 lines
71 KiB
Racket
#lang scribble/doc
|
|
@(require scribble/manual
|
|
(except-in "utils.rkt" url)
|
|
"struct-hierarchy.rkt"
|
|
(for-label scribble/manual-struct
|
|
racket/serialize
|
|
file/convertible
|
|
setup/main-collects
|
|
scriblib/render-cond
|
|
xml/xexpr
|
|
net/url-structs
|
|
(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, 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
|
|
uncollapsable 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{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}.}
|
|
|
|
]
|
|
|
|
@; ------------------------------------------------------------------------
|
|
|
|
@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{@racket['index] --- The part represents an index.}
|
|
|
|
]
|
|
|
|
The recognized @tech{style properties} are as follows:
|
|
|
|
@itemize[
|
|
|
|
@item{@racket['unnumbered] --- A section number is not computed or
|
|
rendered for the section.}
|
|
|
|
@item{@racket['hidden-number] --- A section number is computed for
|
|
the section, but it is not rendered as part of the section name.}
|
|
|
|
@item{@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{@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{@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 patent'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{@racket['toc] --- Sub-parts of the part are rendered on separate
|
|
pages for multi-page HTML mode.}
|
|
|
|
@item{@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{@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{@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{@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{@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{@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.}
|
|
|
|
]
|
|
|
|
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.
|
|
|
|
}
|
|
|
|
|
|
@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{@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{@racket['pretitle] --- Typeset before the title of the
|
|
enclosing part.}
|
|
|
|
@item{@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{@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{@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{@racket[body-id] structure --- For HTML, uses the given string
|
|
as an @tt{id} attribute of the @tt{<p>}, @tt{<div>}, or
|
|
alternate tag.}
|
|
|
|
@item{@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{@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{@racket['centered] --- Centers HTML output horizontally.}
|
|
|
|
@item{@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{@racket[body-id] structure --- For HTML, uses the given string
|
|
as an @tt{id} attribute of the @tt{<table>} tag.}
|
|
|
|
@item{@racket['aux] --- For HTML, include the table in the
|
|
table-of-contents display for the enclosing part.}
|
|
|
|
@item{@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{@racket['compact] --- Reduces space between items.}
|
|
|
|
@item{@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{@racket[body-id] structure --- For HTML, uses the given string
|
|
as an @tt{id} attribute of the @tt{<ul>} or @tt{<ol>} tag.}
|
|
|
|
@item{@racket['never-indents] --- For Latex and @tech{compound
|
|
paragraphs}; see @racket[compound-paragraph].}
|
|
|
|
]}
|
|
|
|
|
|
@defstruct[nested-flow ([style any/c]
|
|
[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{@racket['inset] --- Insets the nested flow relative to
|
|
surrounding text.}
|
|
|
|
@item{@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{@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{@racket['command] --- For Latex output, a string @tech{style
|
|
name} is used as a command name instead of an environment
|
|
name.}
|
|
|
|
@item{@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{@racket[body-id] structure --- For HTML, uses the given string
|
|
as an @tt{id} attribute of the @tt{<blockquote>} tag.}
|
|
|
|
@item{@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{@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{@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{@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{@racket[body-id] structure --- For HTML, uses the given string
|
|
as an @tt{id} attribute of the @tt{<p>} or alternate tag.}
|
|
|
|
@item{@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 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{@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{@racket['hspace] --- Renders its @racket[content] as monospace
|
|
blanks.}
|
|
|
|
@item{@racket['newline] --- Renders a line break independent of
|
|
the @racket[content].}
|
|
|
|
@item{@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[body-id] structure --- For HTML uses the given
|
|
string as an @tt{id} attribute of the @tt{<span>} tag.}
|
|
|
|
@item{@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{@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{@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].}]}
|
|
|
|
|
|
@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?])]{
|
|
|
|
Hyperlinks the content to @racket[_tag].
|
|
|
|
When @racket[_tag] is a part tag and the content of the element is
|
|
@racket[null], then the hyperlink uses the target part's number and/or
|
|
title as the content. In that case, if the section number is preceded
|
|
by a word, the word starts in uppercase if the element's style includes a
|
|
@racket['uppercase] property.
|
|
|
|
The following symbol is recognized as a @tech{style property}:
|
|
|
|
@itemize[
|
|
|
|
@item{@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).}
|
|
|
|
]}
|
|
|
|
|
|
@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 "6.4" @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{@racket['left] --- Left-align the cell content.}
|
|
|
|
@item{@racket['right] --- Right-align the cell content top baselines.}
|
|
|
|
@item{@racket['center] --- Center the cell content horizontally.}
|
|
|
|
@item{@racket['top] --- Top-align the cell content.}
|
|
|
|
@item{@racket['baseline] --- Align the cell content top baselines.}
|
|
|
|
@item{@racket['bottom] --- bottom-align the cell content.}
|
|
|
|
@item{@racket['vcenter] --- Center the cell content vertically.}
|
|
|
|
@item{@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{@racket['left-border], @racket['right-border],
|
|
@racket['top-border], or @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 "6.4"]}
|
|
|
|
|
|
@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 "6.4"]}
|
|
|
|
|
|
@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[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
|
|
to the top of the generated HTML page.
|
|
|
|
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.}
|
|
|
|
|
|
@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[render-convertible-as ([types (listof (or/c 'png-bytes 'svg-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.
|
|
}
|
|
|
|
@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
|
|
a 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"]
|
|
}
|