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

Extracted manual-scheme.rkt and racket.rkt from upstream scribble repository

Browse Source
This commit is contained in:
Georges Dupéron 2016-09-20 18:35:21 +02:00
parent a69f6c6982
commit bbe51a11aa
361 changed files with 0 additions and 45886 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
.gitignore vendored
View File

@ -1,10 +0,0 @@
# Racket compiled files
compiled/
# common backups, autosaves, lock files, OS meta-files
*~
\#*
.#*
.DS_Store
*.bak
TAGS

0
scribble-lib/scribble/private/manual-scheme.rkt → manual-scheme.rkt
View File

0
scribble-lib/scribble/racket.rkt → racket.rkt
View File

11
scribble-doc/LICENSE.txt
View File

@ -1,11 +0,0 @@
scribble-doc
Copyright (c) 2010-2014 PLT Design Inc.
This package is distributed under the GNU Lesser General Public
License (LGPL). This means that you can link this package into proprietary
applications, provided you follow the rules stated in the LGPL. You
can also modify this package; if you distribute a modified version,
you must distribute it under the terms of the LGPL, which in
particular means that you must release the source code for the
modified software. See http://www.gnu.org/copyleft/lesser.html
for more information.

28
scribble-doc/info.rkt
View File

@ -1,28 +0,0 @@
#lang info
(define collection 'multi)
(define build-deps '("racket-index"
"mzscheme-doc"
"net-doc"
"scheme-lib"
"draw-doc"
"gui-doc"
"slideshow-doc"
"pict-doc"
"typed-racket-doc"
"at-exp-lib"
"base"
"compatibility-lib"
"draw-lib"
"pict-lib"
"sandbox-lib"
"slideshow-lib"
"scribble-lib"
"scribble-text-lib"
"racket-doc"))
(define update-implies '("scribble-lib"))
(define pkg-desc "documentation part of \"scribble\"")
(define pkg-authors '(mflatt eli))

793
scribble-doc/scribblings/scribble/base.scrbl
View File

@ -1,793 +0,0 @@
#lang scribble/doc
@(require scribble/manual "utils.rkt"
(for-syntax racket/base)
(for-label setup/main-collects
racket/runtime-path))
@(define-syntax def-section-like
(syntax-rules ()
[(_ id result/c x ...)
(defproc (id [#:tag tag (or/c #f string? (listof string?)) #f]
[#:tag-prefix tag-prefix (or/c #f string? module-path?) #f]
[#:style style (or/c style? #f string? symbol? (listof symbol?)) #f]
[pre-content pre-content?] (... ...+))
result/c
x ...)]))
@(define-syntax def-elem-proc
(syntax-rules ()
[(_ id x ...)
(defproc (id [pre-content pre-content?] (... ...))
element?
x ...)]))
@(define-syntax def-style-proc
(syntax-rules ()
[(_ id)
@def-elem-proc[id]{Like @racket[elem], but with style @racket['id].}]))
@title[#:tag "base"]{Base Document Format}
@defmodulelang[scribble/base]{The @racketmodname[scribble/base]
language provides functions and forms that can be used from code
written either in Racket or with @elem["@"] expressions. It
essentially extends @racketmodname[racket/base], except that top-level
forms within a module using the @racketmodname[scribble/base] language
are treated as document content (like @racketmodname[scribble/doclang]).
The @racketmodname[scribble/base] name can also be used as a library
with @racket[require], in which case it provides only the bindings
defined in this section, and it also does not set the reader or
set the default rendering format to the Racket manual format.}
Functions provided by this library, such as @racket[title] and
@racket[italic], might be called from Racket as
@racketblock[
(title #:tag "how-to"
"How to Design " (italic "Great") " Programs")
]
They can also be called with @elem["@"] notation as
@verbatim[#:indent 2]|{
@title[#:tag "how-to"]{How to Design @italic{Great} Programs}
}|
Although the procedures are mostly designed to be used from @elem["@"]
mode, they are easier to document in Racket mode (partly because we
have @racketmodname[scribble/manual]).
@; ------------------------------------------------------------------------
@section{Document Structure}
@defproc[(title [#:tag tag (or/c #f string? (listof string?)) #f]
[#:tag-prefix tag-prefix (or/c #f string? module-path?) #f]
[#:style style (or/c style? #f string? symbol? (listof symbol?)) #f]
[#:version vers (or/c string? #f) #f]
[#:date date (or/c string? #f) #f]
[pre-content pre-content?] ...+)
title-decl?]{
Generates a @racket[title-decl] to be picked up by @racket[decode] or
@racket[decode-part]. The @tech{decode}d @racket[pre-content] (i.e.,
parsed with @racket[decode-content]) supplies the title content. If
@racket[tag] is @racket[#f], a tag string is generated automatically
from the content. The tag string is combined with the symbol
@racket['part] to form the full tag.
The @racket[style] argument can be a style structure, or it can be one
of the following: a @racket[#f] that corresponds to a ``plain'' style,
a string that is used as a @tech{style name}, a symbol that is used as
a @tech{style property}, or a list of symbols to be used as @tech{style properties}.
For information on styles, see @racket[part]. For example, a style of
@racket['toc] causes sub-sections to be generated as separate pages in
multi-page HTML output.
The @racket[tag-prefix] argument is propagated to the generated
structure (see @secref["tags"]). If @racket[tag-prefix] is a module
path, it is converted to a string using
@racket[module-path-prefix->string].
The @racket[vers] argument is propagated to the @racket[title-decl]
structure. Use @racket[""] as @racket[vers] to suppress version
rendering in the output.
The @racket[date] argument is propagated to the @racket[title-decl]
structure via a @racket[document-date] @tech{style property}. Use
@racket[""] as @racket[date] to suppress date rendering in Latex
output.
The section title is automatically indexed by
@racket[decode-part]. For the index key, leading whitespace and a
leading ``A'', ``An'', or ``The'' (followed by more whitespace) is
removed.}
@def-section-like[section part-start?]{ Like @racket[title], but
generates a @racket[part-start] of depth @racket[0] to be by
@racket[decode] or @racket[decode-part].}
@def-section-like[subsection part-start?]{ Like @racket[section], but
generates a @racket[part-start] of depth @racket[1].}
@def-section-like[subsubsection part-start?]{ Like @racket[section], but
generates a @racket[part-start] of depth @racket[2].}
@def-section-like[subsubsub*section paragraph?]{ Similar to
@racket[section], but merely generates a paragraph that looks like an
unnumbered section heading (for when the nesting gets too deep to
include in a table of contents).}
@defform[(include-section module-path)]{ Requires @racket[module-path]
and returns its @racket[doc] export (without making any imports
visible to the enclosing context). Since this form expands to
@racket[require], it must be used in a module or top-level context.}
@defproc[(author [auth content?] ...) block?]{
Generates a @racket[paragraph] with style name @racket['author] to
show the author(s) of a document, where each author is represented by
@tech{content}. Normally, this function is used after
@racket[title] for the beginning of a document. See also
@racket[author+email].}
@defproc[(author+email [author-name content?]
[email string?]
[#:obfuscate? obfuscate? any/c #f])
element?]{
Combines an author name with an e-mail address. If @racket[obfuscate?]
is true, then the result obscures the e-mail address slightly to avoid
address-harvesting robots.
Note that @racket[author+email] is not a replacement for
@racket[author]. The @racket[author+email] function is often used in
combination with @racket[author].}
@; ------------------------------------------------------------------------
@section{Blocks}
@defproc[(para [#:style style (or/c style? string? symbol? #f) #f]
[pre-content pre-content?] ...) paragraph?]{
Creates a @tech{paragraph} containing the @tech{decode}d
@racket[pre-content] (i.e., parsed with @racket[decode-paragraph]).
The @racket[style] argument can be a style, @racket[#f] to indicate a
``plain'' style, a string that is used as a @tech{style name}, or a
symbol that is used as a @tech{style name}. (Note that
@racket[section] and @racket[para] treat symbols differently as
@racket[style] arguments.)}
@defproc[(nested [#:style style (or/c style? string? symbol? #f) #f]
[pre-flow pre-flow?] ...) nested-flow?]{
Creates a @tech{nested flow} containing the @tech{decode}d
@racket[pre-flow] (i.e., parsed with @racket[decode-flow]).
The @racket[style] argument is handled the same as @racket[para]. The
@racket['inset] and @racket['code-inset] styles cause the nested flow
to be inset compared to surrounding text, with the latter
particularly intended for insetting code. The default style is
specified by the output destination (and tends to inset text for HTML
output and not inset for Latex output).}
@defproc[(centered [pre-flow pre-flow?] ...) nested-flow?]{
Produces a @tech{nested flow} whose content is centered.}
@defproc[(margin-note [pre-flow pre-flow?] ...
[#:left? left? any/c #f])
block?]{
Produces a @tech{nested flow} that is typeset in the margin, instead
of inlined.
If @racket[left?] is true, then the note is shown on the opposite as
it would normally be shown (which is the left-hand side for HTML
output). Beware of colliding with output for a table of contents.}
@defproc[(margin-note* [pre-content pre-content?] ...
[#:left? left? any/c #f])
element?]{
Produces an @racket[element] that is typeset in the margin, instead of
inlined. Unlike @racket[margin-note], @racket[margin-note*] can be
used in the middle of a paragraph; at the same time, its content is
constrained to form a single paragraph in the margin.}
@defproc[(itemlist [itm items/c] ...
[#:style style (or/c style? string? symbol? #f) #f])
itemization?]{
Constructs an @racket[itemization] given a sequence of items. Typical
each @racket[itm] is constructed by @racket[item], but an
@racket[itm] can be a @tech{block} that is coerced to an
@racket[item]. Finally, @racket[itm] can be a list or @racket[splice]
whose elements are spliced (recursively, if necessary) into the
@racket[itemlist] sequence.
The @racket[style] argument is handled the same as @racket[para]. The
@racket['ordered] style numbers items, instead of just using a
bullet.}
@defthing[items/c flat-contract?]{
A contract that is equivalent to the following recursive
specification:
@racketblock[
(or/c item? block? (listof items/c) (spliceof items/c))
]}
@defproc[(item [pre-flow pre-flow?] ...) item?]{
Creates an item for use with @racket[itemlist]. The @tech{decode}d
@racket[pre-flow] (i.e., parsed with @racket[decode-flow]) is the item
content.}
@defproc[(item? [v any/c]) boolean?]{
Returns @racket[#t] if @racket[v] is an item produced by
@racket[item], @racket[#f] otherwise.}
@defproc[(tabular [cells (listof (listof (or/c block? content? 'cont)))]
[#:style style (or/c style? string? symbol? #f) #f]
[#:sep sep (or/c block? content? #f) #f]
[#:column-properties column-properties (listof any/c) '()]
[#:row-properties row-properties (listof any/c) '()]
[#:cell-properties cell-properties (listof (listof any/c)) '()])
table?]{
Creates a @tech{table} with the given @racket[cells] content, which is
supplied as a list of rows, where each row has a list of cells. The
length of all rows must match.
Use @racket['cont] in @racket[cells] as a cell to continue the content
of the preceding cell in a row in the space that would otherwise be
used for a new cell. A @racket['cont] must not appear as the first
cell in a row.
The @racket[style] argument is handled the same as @racket[para].
If @racket[sep] is not @racket[#f], it is inserted as a new column
between every column in the table; note that any
@racket[table-columns] or @racket[table-cells] property in
@racket[style] must take the added columns into account. Otherwise,
the default style places no space between table columns. When @racket[sep]
would be placed before a @racket['cont], a @racket['cont] is inserted,
instead.
The @racket[column-properties], @racket[row-properties], and
@racket[cell-properties] arguments specify @tech{style properties} for
the columns and cells of a table; see @racket[table-columns] and
@racket[table-cells] for a description of recognized properties. The
lists do not contain entries for columns potentially introduced for
@racket[sep], and when non-empty, they are extended as needed to match
the table size determined by @racket[cells]:
@itemlist[
@item{If the length of @racket[column-properties] is less than the
length of each row in @racket[cells], the last item of the list
is duplicated to make the list long enough.}
@item{If the length of @racket[row-properties] is less than the
length of @racket[cells], the last item of the list is
duplicated to make the list long enough.}
@item{If the length of @racket[cell-properties] is less than the
number of rows in @racket[cells], then the last element is
duplicated to make the list long enough. Each list within
@racket[cell-properties] is treated like a
@racket[column-properties] list---expanded as needed to match
the number of columns in each row.}
]
Each element of @racket[column-properties] or @racket[row-properties]
is either a list of @tech{style property} values or a non-list element
that is wrapped as a list. Similarly, for each list that is an element
of @racket[cell-properties], the list's non-list elements are wrapped
as nested lists.
If @racket[column-properties] is non-empty, then its list of property
lists is converted into a @racket[table-columns] @tech{style property}
that is added to the style specified by @racket[style]---or merged
with an existing @racket[table-columns] @tech{style property} that
matches the column shape of @racket[cells]. In addition, if either
@racket[row-properties] or @racket[cell-properties] is non-empty, the
property lists of @racket[column-properties] are merged
with the property lists of @racket[row-properties] and
@racket[cell-properties]. If @racket[row-properties] or
@racket[cell-properties] is non-empty, the merged lists are
converted into a @racket[table-cells] @tech{style property} that is
added to the style specified by @racket[style]---or merged with an
existing @racket[table-cells] @tech{style property} that matches the
shape of @racket[cells].
@margin-note{If the style lists for @racket[column-properties] are
both merged with @racket[cell-properties] and converted to
@racket[table-columns], then @racket[style] will contain some
redundant information. In that case, @racket[column-attributes]
properties will be used from @racket[table-columns], while other
properties will be used from the merger into @racket[table-cells].}
@history[#:changed "1.1" @elem{Added the @racket[#:column-properties],
@racket[#:row-properties],
and @racket[#:cell-properties] arguments.}
#:changed "1.12" @elem{Changed @racket[sep] insertion before a
@racket['cont].}]
Examples:
@codeblock[#:keep-lang-line? #f]|{
#lang scribble/manual
@tabular[#:sep @hspace[1]
(list (list "soup" "gazpacho")
(list "soup" "tonjiru"))]
@tabular[#:style 'boxed
#:column-properties '(left right)
#:row-properties '(bottom-border ())
(list (list @bold{recipe} @bold{vegetable})
(list "caldo verde" "kale")
(list "kinpira gobō" "burdock")
(list "makizushi" 'cont))]
}|
@doc-render-examples[
@tabular[#:sep @hspace[1]
(list (list "soup" "gazpacho")
(list "soup" "tonjiru"))]
@tabular[#:style 'boxed
#:column-properties '(left right)
#:row-properties '(bottom-border ())
(list (list @bold{recipe} @bold{vegetable})
(list "caldo verde" "kale")
(list "kinpira gobō" "burdock")
(list "makizushi" 'cont))]]
}
@defproc[(verbatim [#:indent indent exact-nonnegative-integer? 0] [elem content?] ...+)
block?]{
Typesets string @racket[elem]s in typewriter font with linebreaks
specified by newline characters in string @racket[elem]s. Consecutive spaces in
the string @racket[elem]s are converted to @racket[hspace] to ensure that they
are all preserved in the output. Additional space (via
@racket[hspace]) as specified by @racket[indent] is added to the
beginning of each line. A non-string @racket[elem] is treated as
content within a single line.
The string @racket[elem]s are @emph{not} decoded with @racket[decode-content],
so @racket[(verbatim "---")] renders with three hyphens instead of an
em dash. Beware, however, that @emph{reading}
@litchar["@"]@racket[verbatim] converts @litchar["@"] syntax
within the argument, and such reading occurs well before
arguments to @racket[verbatim] are delivered at run-time. To disable simple
@litchar["@"] notation within the @racket[verbatim] argument,
@racket[verbatim] is typically used with
@litchar["|{"]...@litchar["}|"] or similar brackets, like this:
@verbatim[#:indent 2]|{
@verbatim|{
Use @bold{---} like this...
}|
}|
which renders as
@verbatim[#:indent 2]|{
Use @bold{---} like this...
}|
while
@verbatim[#:indent 2]||{
@verbatim|{
Use |@bold{---} like this...
}|
}||
renders as
@verbatim[#:indent 2]|{
Use |@bold{---} like this...
}|
Even with brackets like @litchar["|{"]...@litchar["}|"], beware that consistent
leading whitespace is removed by the parser; see
@secref["alt-body-syntax"] for more information.
See also @racket[literal].}
@; ------------------------------------------------------------------------
@section{Text Styles and Content}
@defproc[(elem [pre-content pre-content?] ...
[#:style style (or/c style? string? symbol? #f) #f])
element?]{
Wraps the @tech{decode}d @racket[pre-content] as an element with style
@racket[style].}
@def-style-proc[italic]
@def-style-proc[bold]
@defproc[(tt [pre-content pre-content?] ...) element?]{
Similar to @racket[elem], but the @racket['tt] style is used for
immediate strings and symbols among the @racket[pre-content]
arguments.
To apply the @racket['tt] style uniformly to all @racket[pre-content]
arguments, use @racket[(elem #:style 'tt pre-content ...)], instead.}
@def-style-proc[subscript]
@def-style-proc[superscript]
@def-elem-proc[smaller]{Like @racket[elem], but with style
@racket['smaller]. When uses of @racket[smaller] are nested, text
gets progressively smaller.}
@def-elem-proc[larger]{Like @racket[elem], but with style
@racket['larger]. When uses of @racket[larger] are nested, text
gets progressively larger.}
@defproc[(emph [pre-content pre-content?] ...) element?]{
The same as @racket[italic].}
@defproc[(literal [str string?] ...+) element?]{
Produces an element containing literally @racket[str]s with no
decoding via @racket[decode-content].
Beware that @litchar["@"] for a @racket[literal] call performs some
processing before delivering arguments to @racket[literal]. The
@racket[literal] form can be used with @litchar["|{"]...@litchar["}|"]
or similar brackets to disable @litchar["@"] notation within the
@racket[literal] argument, like this:
@verbatim[#:indent 2]|{
@literal|{@bold{---}}|
}|
which renders as
@verbatim[#:indent 2]{
@literal|{@bold{---}}|
}
See also @racket[verbatim].}
@; ------------------------------------------------------------------------
@section[#:tag "images"]{Images}
@defproc[(image [path (or/c path-string? (cons/c 'collects (listof bytes?)))]
[#:scale scale real? 1.0]
[#:suffixes suffixes (listof #rx"^[.]") null]
[#:style style (or/c style? string? symbol? #f) #f]
[pre-content pre-content?] ...)
image-element?]{
Creates an image element from the given path. The @tech{decode}d
@racket[pre-content] serves as the alternate text for contexts where
the image cannot be displayed.
If @racket[path] is a relative path, it is relative to the current
directory, which is set by @exec{raco setup} to
the directory of the main document file. (In general, however, it's
more reliable to express relative paths using
@racket[define-runtime-path].) Instead of a path or string,
the @racket[path] argument can be a result of
@racket[path->main-collects-relative].
The @racket[scale] argument sets the images scale relative to its
default size as determined by the content of @racket[path]. For HTML
output, the resulting @racket[image-element] is rendered with an
@tt{img} or @tt{object} (for SVG) tag, and @racket[scale] adjusts the
@tt{width} and @tt{height} attributes; a class name or other
attributes in @racket[style] can effectively override that size.
The strings in @racket[suffixes] are filtered to those supported by
given renderer, and then the acceptable suffixes are tried in
order. The HTML renderer supports @racket[".png"],
@racket[".gif"], and @racket[".svg"], while the Latex renderer supports @racket[".png"],
@racket[".pdf"], and @racket[".ps"] (but @racket[".ps"] works only
when converting Latex output to DVI, and @racket[".png"] and
@racket[".pdf"] work only for converting Latex output to PDF).
Note that when the @racket[suffixes] list is non-empty, then
the @racket[path] argument should not have a suffix.
@history[#:changed "1.3" @elem{Added the @racket[#:style] argument.}]}
@; ------------------------------------------------------------------------
@section[#:tag "spacing"]{Spacing}
@defproc[(linebreak) element?]{
Produces an element that forces a line break.}
@def-elem-proc[nonbreaking]{Like @racket[elem], but line breaks are
suppressed while rendering the content.}
@defproc[(hspace [n exact-nonnegative-integer?]) element?]{
Produces an element containing @racket[n] spaces and style
@racket['hspace].}
@defthing[~ string?]{
A string containing the non-breaking space character,
which is equivalent to @racket['nbsp] as an element.}
@defthing[-~- string?]{
A string containing the non-breaking hyphen character.}
@defthing[?- string?]{
A string containing the soft-hyphen character (i.e., a suggestion of
where to hyphenate a word to break it across lines when rendering).}
@defthing[._ element?]{
Generates a period that ends an abbreviation in the middle of a
sentence, as opposed to a period that ends a sentence (since the
latter may be typeset with extra space). Use @litchar|{@._}| in a
document instead of just @litchar{.} for an abbreviation-ending period
that is preceded by a lowercase letter and followed by a space.
See @racket[.__] for an example.}
@defthing[.__ element?]{
Generates a period that ends a sentence (which may be typeset with
extra space), as opposed to a period that ends an abbreviation in the
middle of a sentence. Use @litchar|{@.__}| in a document instead of just
@litchar{.} for a sentence-ending period that is preceded by an
uppercase letter.
The following example illustrates both @racket[._] and @racket[.__]:
@codeblock|{
#lang scribble/base
My name is Mr@._ T@.__ I pity the fool who can't typeset punctuation.
}|}
@; ------------------------------------------------------------------------
@section[#:tag "base-links"]{Links}
@defproc[(hyperlink [url string?] [pre-content pre-content?] ...
[#:underline? underline? any/c #t]
[#:style style (or/c style? string? symbol? #f) (if underline? #f "plainlink")])
element?]{
The @tech{decode}d @racket[pre-content] is hyperlinked to
@racket[url]. If @racket[style] is not supplied, then
@racket[underline?] determines how the link is rendered.}
@defproc[(url [dest string?]) element?]{
Generates a literal hyperlinked URL.}
@defproc[(secref [tag string?]
[#:doc module-path (or/c module-path? #f) #f]
[#:tag-prefixes prefixes (or/c (listof string?) #f) #f]
[#:underline? underline? any/c #t])
element?]{
Inserts a reference to the section tagged @racket[tag].
If @racket[#:doc module-path] is provided, the @racket[tag] refers to
a tag with a prefix determined by @racket[module-path]. When
@exec{raco setup} renders documentation, it automatically adds a tag
prefix to the document based on the source module. Thus, for example,
to refer to a section of the Racket reference,
@racket[module-path] would be @racket['(lib
"scribblings/reference/reference.scrbl")].
The @racket[#:tag-prefixes prefixes] argument similarly supports
selecting a particular section as determined by a path of tag
prefixes. When a @racket[#:doc] argument is provided, then
@racket[prefixes] should trace a path of tag-prefixed subsections to
reach the @racket[tag] section. When @racket[#:doc] is not provided,
the @racket[prefixes] path is relative to any enclosing section (i.e.,
the youngest ancestor that produces a match).
For HTML output, 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. If @racket[underline?] is @racket[#f], then the hyperlink is
rendered in HTML without an underline.
For Latex output, the generated reference's format depends on the
document style. By default, only the section number is shown in the
reference, but the @racketmodname[scribble/manual] style shows the
title after the section number. Customize the output (see
@secref["config"]) by redefining the @ltx{BookRef}, @|etc|, macros (see
@secref["builtin-latex"]).
In Racket documentation that is rendered to HTML, clicking on a
section title normally shows the @racket[secref] call that is needed
to link to the section.}
@defproc[(Secref [tag string?]
[#:doc module-path (or/c module-path? #f) #f]
[#:tag-prefixes prefixes (or/c (listof string?) #f) #f]
[#:underline? underline? any/c #t])
element?]{
Like @racket[secref], but if the rendered form of the reference starts
with a word (e.g., ``section''), then the word is capitalized.}
@defproc[(seclink [tag string?]
[#:doc module-path (or/c module-path? #f) #f]
[#:tag-prefixes prefixes (or/c (listof string?) #f) #f]
[#:underline? underline? any/c #t]
[#:indirect? indirect? any/c #f]
[pre-content pre-content?] ...) element?]{
Like @racket[secref], but the link label is the @tech{decode}d
@racket[pre-content] instead of the target section's name.
In addition to @racket[secref]'s arguments, @racket[seclink] supports
a @racket[indirect?] argument. When @racket[indirect?] is true, then
the section hyperlink's resolution in HTML is potentially delayed; see
@racket['indirect-link] for @racket[link-element].}
@defproc[(other-doc [module-path module-path?]
[#:underline? underline? any/c #t]
[#:indirect indirect (or/c #f content?) #f])
element?]{
Like @racket[secref] for the document's implicit @racket["top"]
tag. Use this function to refer to a whole manual instead of
@racket[secref], in case a special style in the future is used for
manual titles.
If @racket[indirect] is not @racket[#f], then the link's resolution in
HTML can be delayed, like @racket[seclink] with @racket[#:indirect?
#t]. The @racket[indirect] content is prefixed with ``the'' and
suffixed with ``documentation'' to generate the rendered text of the
link. For example:
@verbatim[#:indent 2]|{
@other-doc['(lib "parsack/parsack/parsack.scrbl")
#:indirect "Parsec implementation in Racket"]
}|
renders as a hyperlink with the text:
@verbatim[#:indent 2]|{
the Parsec implementation in Racket documentation
}|}
@defproc[(elemtag [t (or/c tag? string?)] [pre-content pre-content?] ...) element?]{
The tag @racket[t] refers to the content form of
@racket[pre-content].}
@defproc[(elemref [t (or/c tag? string?)] [pre-content pre-content?] ...
[#:underline? underline? any/c #t]) element?]{
The @tech{decode}d @racket[pre-content] is hyperlinked to @racket[t],
which is normally defined using @racket[elemtag].}
@; ------------------------------------------------------------------------
@section[#:tag "base-indexing"]{Indexing}
@defproc[(index [words (or/c string? (listof string?))]
[pre-content pre-content?] ...)
index-element?]{
Creates an index element given a plain-text string---or list of
strings for a hierarchy, such as @racket['("strings" "plain")] for a
``plain'' entry below a more general ``strings'' entry. As index keys,
the strings are ``cleaned'' using @racket[clean-up-index-strings]. The
strings (without clean-up) also serve as the text to render in the
index. The @tech{decode}d @racket[pre-content] is the text to appear
inline as the index target.
Use @racket[index] when an index entry should point to a specific word
or phrase within the typeset document (i.e., the
@racket[pre-content]). Use @racket[section-index], instead, to create
an index entry that leads to a section, instead of a specific word or
phrase within the section.}
@defproc[(index* [words (listof string?)]
[word-contents (listof list?)]
[pre-content pre-content?] ...)
index-element?]{
Like @racket[index], except that @racket[words] must be a list, and
the list of contents render in the index (in parallel to
@racket[words]) is supplied as @racket[word-contents].
}
@defproc[(as-index [pre-content pre-content?] ...)
index-element?]{
Like @racket[index], but the word to index is determined by applying
@racket[content->string] on the @tech{decode}d @racket[pre-content].}
@defproc[(section-index [word string?] ...)
part-index-decl?]{
Creates a @racket[part-index-decl] to be associated with the enclosing
section by @racket[decode]. The @racket[word]s serve as both the keys
and as the rendered forms of the keys within the index.}
@defproc[(index-section [#:tag tag (or/c #f string?) "doc-index"])
part?]{
Produces a part that shows the index the enclosing document. The
optional @racket[tag] argument is used as the index section's tag.}
@; ------------------------------------------------------------------------
@section{Tables of Contents}
@defproc[(table-of-contents) delayed-block?]{
Returns a delayed flow element that expands to a table of contents for
the enclosing section. For Latex output, however, the table of
contents currently spans the entire enclosing document.}
@defproc[(local-table-of-contents [#:style style (or/c symbol? #f) #f])
delayed-block?]{
Returns a delayed flow element that may expand to a table of contents
for the enclosing section, depending on the output type. For
multi-page HTML output, the flow element is a table of contents; for
Latex output, the flow element is empty.
The meaning of the @racket[style] argument depends on the output type,
but @racket['immediate-only] normally creates a table of contents that
contains only immediate sub-sections of the enclosing section. See
also the @racket['quiet] style of @racket[part] (i.e., in a
@racket[part] structure, not supplied as the @racket[style] argument
to @racket[local-table-of-contents]), which normally suppresses
sub-part entries in a table of contents.}
@; ------------------------------------------------------------------------
@section{Tags}
The exports of @racketmodname[scribble/tag] are all re-exported by
@racketmodname[scribble/base].

26
scribble-doc/scribblings/scribble/basic.scrbl
View File

@ -1,26 +0,0 @@
#lang scribble/manual
@(require "utils.rkt" (for-label (only-in scribble/basic span-class)))
@(define (compat)
@italic{For backward compatibility.})
@title[#:tag "basic"]{Compatibility Basic Functions}
@defmodule[scribble/basic]{The @racketmodname[scribble/basic]
compatibility library mostly just re-exports
@racketmodname[scribble/base].}
@defproc[(span-class [style-name string?] [pre-content any/c] ...)
element?]{
@compat[] Wraps the @tech{decode}d
@racket[pre-content] as an element with style @racket[style-name].}
@defproc[(itemize [itm (or/c whitespace? an-item?)] ...
[#:style style (or/c style? string? symbol? #f) #f])
itemization?]{
@compat[] Like @racket[itemlist], but whitespace strings among the
@racket[itm]s are ignored.}

59
scribble-doc/scribblings/scribble/blueboxes.scrbl
View File

@ -1,59 +0,0 @@
#lang scribble/doc
@(require scribble/manual "utils.rkt"
(for-label scribble/core
scribble/blueboxes
racket/contract
setup/xref))
@title[#:tag "blueboxes"]{Blue Boxes Utilities}
@defmodule[scribble/blueboxes]{
The @racketmodname[scribble/blueboxes] provides access
to the content of the ``blue boxes'' that describe
some module's export (but without any styling).}
@defproc[(fetch-blueboxes-strs [tag tag?]
[#:blueboxes-cache blueboxes-cache
blueboxes-cache?
(make-blueboxes-cache #t)])
(or/c #f (non-empty-listof string?))]{
Returns a list of strings that show the content of the blue box
(without any styling information) for the documentation referenced
by @racket[tag].
The first string in the list describes the export (e.g. @racket["procedure"]
when @racket[defproc] is used, or @racket["syntax"] when @racket[defform]
was used to document the export).
}
@defproc[(fetch-blueboxes-method-tags [method-name symbol?]
[#:blueboxes-cache blueboxes-cache
blueboxes-cache?
(make-blueboxes-cache #t)])
(listof method-tag?)]{
Returns the list of tags for all methods that are documented in the documentation
in @racket[blueboxes-cache].
@history[#:added "1.11"]
}
@defproc[(make-blueboxes-cache
[populate? boolean?]
[#:blueboxes-dirs blueboxes-dirs (listof path?) (get-doc-search-dirs)])
blueboxes-cache?]{
Constructs a new (mutable) blueboxes cache.
If @racket[populate?] is @racket[#f], the cache is initially
unpopulated, in which case it is filled in the first time the cache
is passed to @racket[fetch-bluebxoes-strs]. Otherwise, the cache is
populated immediately.
The @racket[blueboxes-dirs] argument is a list of directories that are
looked inside for @filepath{blueboxes.rktd} files. The default value
is only an approximation for where those files usually reside. See
also @racket[get-rendered-doc-directories].
}
@defproc[(blueboxes-cache? [v any/c]) boolean?]{
Determines if @racket[v] is a blueboxes cache.
}

97
scribble-doc/scribblings/scribble/bnf.scrbl
View File

@ -1,97 +0,0 @@
#lang scribble/doc
@(require scribble/manual "utils.rkt" scribble/bnf
(for-label scribble/bnf))
@title[#:tag "bnf"]{BNF Grammars}
@defmodule[scribble/bnf]{The @racket[scribble/bnf] library
provides utilities for typesetting grammars.}
For example,
@verbatim[#:indent 2]|{
@(let ([open @litchar{(}]
[close @litchar{)}])
@BNF[(list @nonterm{expr}
@nonterm{id}
@BNF-seq[open @kleeneplus[@nonterm{expr}] close]
@BNF-seq[open @litchar{lambda}
open @kleenestar[@nonterm{id}] close
@nonterm{expr} close]
@nonterm{val})
(list @nonterm{val}
@BNF-alt[@nonterm{number} @nonterm{primop}])
(list @nonterm{id}
@elem{any name except for @litchar{lambda}})])
}|
produces the output
@(let ([open @litchar{(}]
[close @litchar{)}])
@BNF[(list @nonterm{expr}
@nonterm{id}
@BNF-seq[open @kleeneplus[@nonterm{expr}] close]
@BNF-seq[open @litchar{lambda}
open @kleenestar[@nonterm{id}] close
@nonterm{expr} close]
@nonterm{val})
(list @nonterm{val}
@BNF-alt[@nonterm{number} @nonterm{primop}])
(list @nonterm{id}
@elem{any name except for @litchar{lambda}})])
See also @racket[racketgrammar].
@defproc[(BNF [prod (cons element? (listof (or/c block? element?)))] ...) table?]{
Typesets a grammar table. Each production starts with an element
(typically constructed with @racket[nonterm]) for the non-terminal
being defined, and then a list of possibilities (typically constructed
with @racket[BNF-seq], etc.) to show on separate lines.}
@defproc[(nonterm (pre-content any/c) ...) element?]{
Typesets a non-terminal: italic in angle brackets.}
@defproc[(BNF-seq [elem element?] ...) element?]{
Typesets a sequence.}
@defproc[(BNF-seq-lines [elems (listof element?)] ...) block?]{
Typesets a sequence that is broken into multiple lines, where each
@racket[elems] is one line.}
@defproc[(BNF-group [pre-content any/c] ...) element?]{
Typesets a group surrounded by curly braces (so the entire group can
be repeated, for example).}
@defproc[(optional [pre-content any/c] ...) element?]{
Typesets an optional element: in square brackets.}
@defproc[(kleenestar [pre-content any/c] ...) element?]{
Typesets a 0-or-more repetition.}
@defproc[(kleeneplus [pre-content any/c] ...) element?]{
Typesets a 1-or-more repetition.}
@defproc[(kleenerange [n any/c] [m any/c] [pre-content any/c] ...) element?]{
Typesets a @racket[n]-to-@racket[m] repetition. The @racket[n] and
@racket[m] arguments are converted to a string using @racket[(format
"~a" n)] and @racket[(format "~a" m)].}
@defproc[(BNF-alt [elem element?] ...) element?]{
Typesets alternatives for a production's right-hand side to appear on
a single line. The result is normally used as a single possibility in
a production list for @racket[BNF].}
@defthing[BNF-etc string?]{
A string to use for omitted productions or content.}

9
scribble-doc/scribblings/scribble/book.scrbl
View File

@ -1,9 +0,0 @@
#lang scribble/manual
@(require "utils.rkt")
@title{Book Format}
@defmodulelang[scribble/book]{The @racketmodname[scribble/book]
language is like @racketmodname[scribble/base], but configured with
Latex style defaults to use the standard @tt{book} class. Top-level
sections are rendered as Latex chapters.}

514
scribble-doc/scribblings/scribble/class-diagrams.rkt
View File

@ -1,514 +0,0 @@
#lang racket/base
(require (prefix-in etc: mzlib/etc)
texpict/mrpict
(only-in pict pin-line pin-arrow-line)
(except-in texpict/utils pin-line pin-arrow-line)
racket/class
racket/runtime-path
racket/draw
racket/contract
(only-in racket/list last))
(define the-font-size 12)
(define prim-font-family 'swiss)
;; Was 'modern, but we want font smoothing even for small text:
(define font-family (make-object font% the-font-size 'modern 'normal 'normal #f 'smoothed))
(define prim-types '("int" "String" "float" "double" "boolean"))
;; how far a dot is to the right of a class
(define dot-edge-spacing 10)
(define field-arrowhead-size 10)
(define hierarchy-color "navy")
(define type-link-color "firebrick")
#|
(define font-family "Palatino")
(define-runtime-path afm "afm")
(current-ps-afm-file-paths (cons afm (current-ps-afm-file-paths)))
(let ([id (send the-font-name-directory find-or-create-font-id font-family 'default)])
(send the-font-name-directory set-post-script-name
id 'normal 'normal "Palatino-Roman")
(send the-font-name-directory set-post-script-name
id 'bold 'normal "Palatino-Bold")
(send the-font-name-directory set-post-script-name
id 'normal 'italic "Palatino-Italic"))
|#
(define (user-type-font x) (text x font-family the-font-size))
(define (prim-type-font x) (text x prim-font-family the-font-size))
(define (var-font x) (text x `(bold . ,font-family) the-font-size))
(define (field-name-font x) (text x font-family the-font-size))
(define (comment-font x) (text x font-family the-font-size))
(define (normal-font x) (text x font-family the-font-size))
(define (java-this) (text "this" `(bold . ,font-family) the-font-size))
;; field-spec : string string -> pict
(define (field-spec type fd #:default [default #f] [comment #f])
(let ([code-line
(hbl-append (if type
(hbl-append (type-spec type)
(normal-font " "))
(blank))
(field-name-font fd)
(if default
(hbl-append (normal-font " = ")
(normal-font default))
(blank))
#;
(normal-font ";"))])
(if comment
(hbl-append code-line
(normal-font " ")
(comment-font (format "[in ~a]" comment)))
code-line)))
(define (method-spec range name #:body [body #f] . args)
(unless (even? (length args))
(error 'method-spec "expected a list of types and argument names, but found ~a arguments"
(length args)))
(let ([first-line
(hbl-append
(type-spec range)
(normal-font " ")
(var-font name)
(cond
[(null? args)
(normal-font "()")]
[else
(hbl-append
(normal-font "(")
(let loop ([args args])
(let* ([type (car args)]
[param (cadr args)]
[single-arg
(if param
(hbl-append (type-spec type)
(normal-font " ")
(var-font param))
(type-spec type))])
(cond
[(null? (cddr args))
(hbl-append single-arg (normal-font ")"))]
[else
(hbl-append single-arg
(normal-font ", ")
(loop (cddr args)))]))))])
(if body
(hbl-append (normal-font " {"))
(blank)))])
(if body
(vl-append first-line
(hbl-append (blank 8 0) body (normal-font "}")))
first-line)))
(define (type-spec str)
(cond
[(member str prim-types) (prim-type-font str)]
[else (user-type-font str)]))
;; class-name : string -> pict
(define (class-name txt #:spacing-word [spacing-word txt])
(define p (colorize (lt-superimpose (ghost (var-font spacing-word))
(apply vl-append (map var-font (regexp-split #rx"\n" txt))))
"white"))
(refocus (cc-superimpose (colorize (filled-rectangle (+ class-box-margin class-box-margin (pict-width p))
(+ class-box-margin class-box-margin (pict-height p)))
"black")
p)
p))
(define class-box-margin 4)
;; class-box : pict (or/c #f (listof pict)) (or/c #f (listof pict)) -> pict
(define (class-box name fields methods)
(let* ([mk-blank (λ () (blank 0 (+ class-box-margin class-box-margin)))])
(cond
[(and methods fields)
(let* ([top-spacer (mk-blank)]
[bottom-spacer (mk-blank)]
[main (vl-append name
top-spacer
(if (null? fields)
(blank 0 4)
(apply vl-append fields))
bottom-spacer
(if (null? methods)
(blank 0 4)
(apply vl-append methods)))])
(add-hline
(add-hline (frame (inset main class-box-margin))
top-spacer)
bottom-spacer))]
[fields
(let* ([top-spacer (mk-blank)]
[main (vl-append name
top-spacer
(if (null? fields)
(blank)
(apply vl-append fields)))])
(add-hline (frame (inset main class-box-margin))
top-spacer))]
[methods (class-box name methods fields)]
[else (frame (inset name class-box-margin))])))
(define (add-hline main sub)
(let-values ([(x y) (cc-find main sub)])
(pin-line main
sub (λ (p1 p2) (values 0 y))
sub (λ (p1 p2) (values (pict-width main) y)))))
;; hierarchy : pict (cons pict (listof pict)) (cons pict (listof pict)) -> pict
(define (hierarchy main supers subs)
(let ([supers-bottoms (apply max (map (λ (x) (let-values ([(x y) (cb-find main x)]) y)) supers))]
[subs-tops (apply min (map (λ (x) (let-values ([(x y) (ct-find main x)]) y)) subs))]
[sorted-subs (sort subs (λ (x y) (< (left-edge-x main x) (left-edge-x main y))))])
(unless (< supers-bottoms subs-tops)
(error 'hierarchy "expected supers to be on top of subs, supers bottom is at ~a, and subs tops is at ~a"
supers-bottoms
subs-tops))
(let* ([main-line-y (max (- subs-tops 20) (/ (+ supers-bottoms subs-tops) 2))]
[main-line-start-x (center-x main (car sorted-subs))]
[main-line-end-x (center-x main (last sorted-subs))]
[w/main-line
(pin-line main
main (λ (_1 _2) (values main-line-start-x main-line-y))
main (λ (_1 _2) (values main-line-end-x main-line-y))
#:color hierarchy-color)]
[super-lines
(map (λ (super)
(let-values ([(x y) (cb-find main super)])
(pin-over
(pin-line (ghost main)
super cb-find
main (λ (_1 _2) (values x main-line-y)))
(- x (/ (pict-width triangle) 2))
(- (/ (+ y main-line-y) 2)
(/ (pict-height triangle) 2))
triangle)))
supers)]
[sub-lines
(map (λ (sub)
(let-values ([(x y) (ct-find main sub)])
(pin-line (ghost main)
sub ct-find
main (λ (_1 _2) (values x main-line-y))
#:color hierarchy-color)))
subs)])
(apply cc-superimpose
w/main-line
(append sub-lines
super-lines)))))
(define triangle-width 12)
(define triangle-height 12)
(define triangle
(let ([points (list (make-object point% (/ triangle-width 2) 0)
(make-object point% 0 triangle-height)
(make-object point% triangle-width triangle-height))])
(colorize
(dc (λ (dc dx dy)
(let ([brush (send dc get-brush)])
(send dc set-brush (send brush get-color) 'solid)
(send dc draw-polygon points dx dy)
(send dc set-brush brush)))
triangle-width
triangle-height)
hierarchy-color)))
(define (center-x main pict)
(let-values ([(x y) (cc-find main pict)])
x))
(define (left-edge-x main pict)
(let-values ([(x y) (lc-find main pict)])
x))
(define (add-dot-right main class field) (add-dot-left-right/offset main class field 0 rc-find))
(define add-dot-right/space
(λ (main class field [count 1])
(add-dot-right/offset main class field (* count dot-edge-spacing))))
(define (add-dot-right/offset main class field offset)
(add-dot-left-right/offset main class field offset rc-find))
(define (add-dot-left main class field) (add-dot-left-right/offset main class field 0 lc-find))
(define add-dot-left/space
(λ (main class field [count 1])
(add-dot-left/offset main class field (* count (- dot-edge-spacing)))))
(define (add-dot-left/offset main class field offset)
(add-dot-left-right/offset main class field offset lc-find))
(define (add-dot-left-right/offset main class field offset finder)
(let-values ([(_1 y) (cc-find main field)]
[(x-edge _2) (finder main class)])
(add-dot main (+ x-edge offset) y)))
(define add-dot-junction
(case-lambda
[(main x-pict y-pict) (add-dot-junction main x-pict cc-find y-pict cc-find)]
[(main x-pict x-find y-pict y-find)
(let-values ([(x _1) (x-find main x-pict)]
[(_2 y) (y-find main y-pict)])
(add-dot main x y))]))
(define (add-dot-offset pict dot dx dy)
(let-values ([(x y) (cc-find pict dot)])
(add-dot pict (+ x dx) (+ y dy))))
(define dot-δx (make-parameter 0))
(define dot-δy (make-parameter 0))
(define (add-dot pict dx dy)
(let ([dot (blank)])
(values (pin-over pict
(+ dx (dot-δx))
(+ dy (dot-δy))
dot)
dot)))
(define (connect-dots show-arrowhead? main dot1 . dots)
(let loop ([prev-dot dot1]
[dots dots]
[pict main])
(cond
[(null? dots) pict]
[else
(loop (car dots)
(cdr dots)
(connect-two-dots pict prev-dot (car dots) (null? (cdr dots)) show-arrowhead?))])))
(define (connect-two-dots pict dot1 dot2 arrowhead? show-arrowhead?)
(if arrowhead?
(pin-arrow-line field-arrowhead-size pict
dot1 cc-find
dot2 cc-find
#:hide-arrowhead? (not show-arrowhead?)
#:color type-link-color)
(pin-line pict
dot1 cc-find
dot2 cc-find
#:color type-link-color)))
(define (hierarchy/layout tops bottoms
#:every-other-space [every-other-space 0]
#:top-space [top-space 40]
#:bottom-space [bottom-space 40]
#:vertical-space [vertical-space 60])
(hierarchy
(vc-append (apply ht-append top-space tops)
(blank 0 vertical-space)
(apply ht-append bottom-space
(let loop ([bottoms bottoms]
[every-other? #f])
(cond
[(null? bottoms) '()]
[else
(cons (if every-other?
(vc-append (blank 0 every-other-space)
(car bottoms))
(car bottoms))
(loop (cdr bottoms)
(not every-other?)))]))))
tops
bottoms))
(define (add-dot-delta f dx dy)
(parameterize ([dot-δx dx]
[dot-δy dy])
(f)))
(define (right-right-reference main0 start-class start-field finish-class finish-name
[count 1]
#:connect-dots [connect-dots connect-dots]
#:dot-delta [dot-delta 0])
(let ([going-down? (let-values ([(_1 start-y) (find-cc main0 start-field)]
[(_2 finish-y) (find-cc main0 finish-name)])
(< start-y finish-y))])
(define-values (main1 dot1) (add-dot-delta (λ () (add-dot-right main0 start-class start-field))
0
(if going-down?
dot-delta
(- dot-delta))))
(define-values (main2 dot2) (add-dot-delta (λ () (add-dot-right/space main1 start-class start-field count))
dot-delta
(if going-down?
dot-delta
(- dot-delta))))
(define-values (main3 dot3) (add-dot-delta (λ () (add-dot-right main2 finish-class finish-name))
0
(if going-down?
(- dot-delta)
dot-delta)))
(define-values (main4 dot4) (add-dot-delta (λ () (add-dot-junction main3 dot2 dot3))
0
0))
;; these last two dots are just there for the delta-less arrowhead
(define-values (main5 dot5) (add-dot-right main4 finish-class finish-name))
(define-values (main6 dot6) (add-dot-delta (λ () (add-dot-right main5 finish-class finish-name))
1 ;; just enough to get the arrowhead going the right direction; not enough to see the line
0))
(connect-dots
#t
(connect-dots #f main6 dot1 dot2 dot4 dot3)
dot6
dot5)))
(define left-left-reference
(λ (main0 start-class start-field finish-class finish-name [count 1]
#:connect-dots [connect-dots connect-dots]
#:dot-delta [dot-delta 0])
(let ([going-down? (let-values ([(_1 start-y) (find-cc main0 start-field)]
[(_2 finish-y) (find-cc main0 finish-name)])
(< start-y finish-y))])
(define-values (main1 dot1) (add-dot-delta (λ () (add-dot-left main0 start-class start-field))
0
(if going-down?
dot-delta
(- dot-delta))))
(define-values (main2 dot2) (add-dot-delta (λ () (add-dot-left/space main1 start-class start-field count))
(- dot-delta)
(if going-down?
dot-delta
(- dot-delta))))
(define-values (main3 dot3) (add-dot-delta (λ () (add-dot-left main2 finish-class finish-name))
0
(if going-down?
(- dot-delta)
dot-delta)))
(define-values (main4 dot4) (add-dot-delta (λ () (add-dot-junction main3 dot2 dot3))
0
0))
(define-values (main5 dot5) (add-dot-left main4 finish-class finish-name))
(define-values (main6 dot6) (add-dot-delta (λ () (add-dot-left main5 finish-class finish-name))
-1 ;; just enough to get the arrowhead going the right direction; not enough to see the line
0))
(connect-dots
#t
(connect-dots #f main6 dot1 dot2 dot4 dot3)
dot6
dot5))))
(define left-top-reference
(λ (main0 start-class start-field finish-class [count 1] #:connect-dots [connect-dots connect-dots])
(define-values (main1 dot1) (add-dot-left main0 start-class start-field))
(define-values (main2 dot2) (add-dot-left/space main1 start-class start-field count))
(define-values (main3 dot3) (add-dot-junction main2 dot2 cc-find finish-class ct-find))
(connect-dots #t main3 dot1 dot2 dot3)))
(define right-left-reference
(λ (main0 start-class start-field finish-class finish-name
[offset
(find-middle main0 start-class rc-find finish-class lc-find)]
#:connect-dots [connect-dots connect-dots])
(define-values (main1 dot1) (add-dot-right main0 start-class start-field))
(define-values (main2 dot2) (add-dot-right/offset main1 start-class start-field offset))
(define-values (main3 dot3) (add-dot-left main2 finish-class finish-name))
(define-values (main4 dot4) (add-dot-junction main3 dot2 dot3))
(connect-dots #t main4 dot1 dot2 dot4 dot3)))
(define left-right-reference
(λ (main0 start-class start-field finish-class finish-name
[offset
(- (find-middle main0 start-class lc-find finish-class rc-find))]
#:connect-dots [connect-dots connect-dots])
(define-values (main1 dot1) (add-dot-left main0 start-class start-field))
(define-values (main2 dot2) (add-dot-left/offset main1 start-class start-field offset))
(define-values (main3 dot3) (add-dot-right main2 finish-class finish-name))
(define-values (main4 dot4) (add-dot-junction main3 dot2 dot3))
(connect-dots #t main4 dot1 dot2 dot4 dot3)))
(define (find-middle main p1 find1 p2 find2)
(let-values ([(x1 y1) (find1 main p1)]
[(x2 y2) (find2 main p2)])
(- (/ (+ x1 x2) 2) (min x1 x2))))
(define right-top-reference
(λ (main0 start-class start-field finish-class [count 1] #:connect-dots [connect-dots connect-dots])
(define-values (main1 dot1) (add-dot-right main0 start-class start-field))
(define-values (main2 dot2) (add-dot-right/space main1 start-class start-field count))
(define-values (main3 dot3) (add-dot-junction main2 dot2 cc-find finish-class ct-find))
(connect-dots #t main3 dot1 dot2 dot3)))
(define connect-dots-contract (->* (boolean? pict? pict?) () #:rest (listof pict?) (values pict?)))
(provide type-link-color)
(provide/contract
[field-spec (->* ((or/c #f string?) string?) (string? #:default string?) pict?)]
[class-name (->* (string?) (#:spacing-word string?) pict?)]
[class-box (-> pict? (or/c false/c (listof pict?)) (or/c false/c (listof pict?)) pict?)]
[hierarchy/layout
(->* ((cons/c pict? (listof pict?)) (cons/c pict? (listof pict?)))
(#:top-space
integer?
#:bottom-space integer?
#:vertical-space integer?
#:every-other-space integer?)
pict?)]
[user-type-font (-> string? pict?)]
[prim-type-font (-> string? pict?)]
[var-font (-> string? pict?)]
[normal-font (-> string? pict?)]
[comment-font (-> string? pict?)]
[hierarchy (-> pict?
(cons/c pict? (listof pict?))
(cons/c pict? (listof pict?))
pict?)]
[right-right-reference (->* (pict? pict? pict? pict? pict?)
(number?
#:connect-dots connect-dots-contract
#:dot-delta number?)
pict?)]
[left-left-reference (->* (pict? pict? pict? pict? pict?)
(number?
#:connect-dots connect-dots-contract
#:dot-delta number?)
pict?)]
[right-left-reference (->* (pict? pict? pict? pict? pict?)
(number?
#:connect-dots connect-dots-contract)
pict?)]
[left-right-reference (->* (pict? pict? pict? pict? pict?)
(number?
#:connect-dots connect-dots-contract)
pict?)]
[left-top-reference (->* (pict? pict? pict? pict?)
(number?
#:connect-dots connect-dots-contract)
pict?)]
[right-top-reference (->* (pict? pict? pict? pict?)
(number?
#:connect-dots connect-dots-contract)
pict?)]
[dot-edge-spacing number?]
[connect-dots connect-dots-contract]
[add-dot-right (-> pict? pict? pict? (values pict? pict?))]
[add-dot-right/space (-> pict? pict? pict? (values pict? pict?))]
[add-dot-left (-> pict? pict? pict? (values pict? pict?))]
[add-dot-left/space (-> pict? pict? pict? (values pict? pict?))]
[add-dot-junction
(case->
(-> pict? pict? pict? (values pict? pict?))
(-> pict?
pict? (-> pict? pict? (values number? number?))
pict? (-> pict? pict? (values number? number?))
(values pict? pict?)))]
[add-dot-offset (-> pict? pict? number? number? (values pict? pict?))]
[add-dot (-> pict? number? number? (values pict? pict?))]
[method-spec
(->* (string? string?)
(#:body (or/c false/c pict?))
#:rest (listof (or/c false/c string?))
pict?)]
[java-this (-> pict?)]
[field-arrowhead-size number?])

6
scribble-doc/scribblings/scribble/compat.scrbl
View File

@ -1,6 +0,0 @@
#lang scribble/manual
@title{Compatibility Libraries}
@include-section["struct.scrbl"]
@include-section["basic.scrbl"]

654
scribble-doc/scribblings/scribble/config.scrbl
View File

@ -1,654 +0,0 @@
#lang scribble/doc
@(require scribble/manual scribble/core scribble/decode
scribble/html-properties scribble/latex-properties
"utils.rkt"
(for-label racket/base
scribble/latex-prefix))
@(define (fake-title . str) (apply bold str))
@(define (css s) (tt s))
@(define spacer @hspace[1])
@(define baseline (style #f '(baseline)))
@(define-syntax-rule (css-table [name desc] ...)
(tabular
#:style (style #f (list (table-columns (list baseline baseline baseline baseline))))
(list (list spacer name spacer @smaller[desc]) ...)))
@; ------------------------------------------------------------
@title[#:tag "config" #:style 'toc]{Extending and Configuring Scribble Output}
Sometimes, Scribble's primitives and built-in styles are insufficient
to produce the output that you need. The cases in which you need to
extend or configure Scribble fall into two groups:
@itemize[
@item{You may need to drop into the back-end ``language'' of CSS or
Latex to create a specific output effect. For this kind of
extension, you will mostly likely attach a
@racket[css-addition] or @racket[tex-addition] @tech{style property}
to style, where the addition implements the style name. This
kind of extension is described in @secref["extra-style"].}
@item{You may need to produce a document whose page layout is
different from the Racket documentation style. For that
kind of configuration, you can run the @exec{scribble} command-line
tool and supply flags like @DFlag{prefix} or @DPFlag{style}, or
you can associate a @racket[html-defaults] or
@racket[latex-defaults] @tech{style property} to the main document's
style. This kind of configuration is described in
@secref["config-style"].}
]
@local-table-of-contents[]
@; ------------------------------------------------------------
@section[#:tag "extra-style"
#:style (make-style #f (list (make-css-addition "inbox.css")
(make-tex-addition "inbox.tex")))
]{Implementing Styles}
When a string is used as a style in an @racket[element],
a @racket[multiarg-element], @racket[paragraph], @racket[table],
@racket[itemization], @racket[nested-flow], or
@racket[compound-paragraph], it corresponds to a CSS class for HTML
output or a Latex macro/environment for Latex output. In Latex output,
the string is used as a command name for a @racket[paragraph]
and an environment name for a @racket[table], @racket[itemization],
@racket[nested-flow], or @racket[compound-paragraph]; if the style has
a @racket['command] @tech{style property} for a @racket[nested-flow] or
@racket[compound-paragraph], then the style name is used as a command
instead of an environment; and if the style has
a @racket['multicommand] @tech{style property} for a @racket[nested-flow],
then the style name is used as a command with multiple arguments.
In addition, for an itemization, the style
string is suffixed with @racket["Item"] and used as a CSS class or Latex
macro name to use for the itemization's items (in place of @ltx{item}
in the case of Latex).
To add a mapping from your own style name to a CSS configuration, add
a @racket[css-addition] structure instance to a style's @tech{style property}
list. To map a style name to a Latex macro or environment, add a
@racket[tex-addition] structure instance. A @racket[css-addition] or
@racket[tex-addition] is normally associated with the style whose name
is implemented by the adition, but it can also be added to the style
for an enclosing part.
Scribble includes a number of predefined styles that are used by the
exports of @racket[scribble/base]. You can use them or redefine
them. The styles are specified by @filepath{scribble.css} and
@filepath{scribble.tex} in the @filepath{scribble} collection.
The styles used by @racketmodname[scribble/manual] are implemented by
@filepath{racket.css} and @filepath{racket.tex} in the
@filepath{scribble} collection. Other libraries, such as
@racketmodname[scriblib/autobib], similarly implement styles through files
that are associated by @racket[css-addition] and @racket[tex-addition]
@tech{style properties}.
To avoid collisions with future additions to Scribble, start your
style name with an uppercase letter that is not @litchar{S}. An
uppercase letter helps to avoid collisions with macros defined by
Latex packages, and future styles needed by @racketmodname[scribble/base] and
@racketmodname[scribble/manual] will start with @litchar{S}.
For example, a Scribble document
@verbatim[#:indent 2]|{
#lang scribble/manual
@(require scribble/core
scribble/html-properties
scribble/latex-properties)
@(define inbox-style
(make-style "InBox"
(list (make-css-addition "inbox.css")
(make-tex-addition "inbox.tex"))))
@title{Quantum Pet}
Do not open: @elem[#:style inbox-style]{Cat}
}|
combined with an @filepath{inbox.css} that contains
@verbatim[#:indent 2]|{
.InBox {
padding: 0.2em;
border: 1px solid #000000;
}
}|
and an @filepath{inbox.tex} that contains
@verbatim[#:indent 2]|{
\newcommand{\InBox}[1]{\fbox{#1}}
}|
generates
@nested[#:style 'inset]{
@fake-title{Quantum Pet}
Do not open: @elem[#:style "InBox"]{Cat}
}
@index["HTML Tags and Attributes"]{
Scribble documents can also embed specific html tags and
attributes.} For example, this Scribble document:
@codeblock|{
#lang scribble/base
@(require scribble/core
scribble/html-properties)
@(define external-image
(elem
#:style
(style #f
(list (alt-tag "img")
(attributes
'((src . "http://racket-lang.org/icon.png")))))))
@external-image
}|
renders as the the Racket logo at the url
@url{http://racket-lang.org/logo.png}
when producing html.
@; ------------------------------------------------------------
@section[#:tag "config-style"]{Configuring Output}
The implementation of styles used by libraries depends to some degree
on separately configurable parameters, and configuration is also
possible by replacing style implementations. Latex output is more
configurable in the former way, since a document class determines a
set of page-layout and font properties that are used by other
commands. The style-replacement kind of configuration corresponds to
re-defining Latex macros or overriding CSS class attributes. When
@exec{raco setup} builds PDF documentation, it uses both kinds of
configuration to produce a standard layout for Racket manuals;
that is, it selects a particular page layout, and it replaces some
@racketmodname[racket/base] styles.
Two kinds of files implement the two kinds of configuration:
@itemize[
@item{A @deftech{prefix file} determines the @tt{DOCTYPE} line for
HTML output or the @ltx{documentclass} configuration (and
perhaps some addition package uses or other configurations) for
Latex output.
The default prefix files are @filepath{scribble-prefix.html}
and @filepath{scribble-prefix.tex} in the @filepath{scribble}
collection.}
@item{A @deftech{style file} refines the implementation of styles
used in the document---typically just the ``built-in'' styles
used by @racketmodname[scribble/base].
The default style files, @filepath{scribble-style.css} and
@filepath{scribble-style.tex} in the @filepath{scribble}
collection, change no style implementations.}
]
For a given configuration of output, typically a particular prefix
file works with a particular style file. Some prefix or style files
may be more reusable. For now, reading the default files is the best
way to understand how they interact. A prefix and/or style file may
also require extra accomanying files; for example, a prefix file for
Latex mode may require a corresponding Latex class file. The default
prefix and style files require no extra files.
When rendering a document through the @exec{scribble} command-line
tool, use flags to select a prefix file, style file, and additional
accompanying files:
@itemize[
@item{Select the prefix file using the @as-index{@DFlag{prefix}}
flag. (Selecting the prefix file also cancels the default list
of accompanying files, if any.)}
@item{Replace the style file using the @as-index{@DFlag{style}}
flag. Add additional style definitions and re-definitions using
the @as-index{@DPFlag{style}} flag.}
@item{Add additional accompanying files with @as-index{@DPFlag{extra}}.}
]
When using the @exec{scribble} command-line utility, a document can
declare its default style, prefix, and extra files through a
@racket[html-defaults] and/or @racket[latex-defaults]
@tech{style property}. In particular, when using the @exec{scribble}
command-line tool to generate Latex or PDF a document whose main part
is implemented with @racket[#, @hash-lang[] #,
@racketmodname[scribble/manual]], the result has the standard
Racket manual configuration, because @racketmodname[scribble/manual]
associates a @racket[latex-defaults] @tech{style property} with the exported
document. The @racketmodname[scribble/sigplan] language similarly
associates a default configuration with an exported document. As
libraries imported with @racket[require], however,
@racketmodname[scribble/manual] and @racketmodname[scribble/sigplan]
simply implement new styles in a composable way.
Whether or not a document has a default prefix- and style-file
configuration through a @tech{style property}, the defaults can be
overridden using @exec{scribble} command-line flags. Furthermore,
languages like @racketmodname[scribble/manual] and
@racketmodname[scribble/sigplan] add a @racket[html-defaults] and/or
@racket[latex-defaults] @tech{style property} to a main-document part only if
it does not already have such a property added through the
@racket[#:style] argument of @racket[title].
@; ------------------------------------------------------------
@section[#:tag "builtin-css"]{Base CSS Style Classes}
The following renderings of @elem[#:style (style #f (list
(link-resource "demo.scrbl")))]{@filepath{demo.scrbl}} demonstrate all
of the CSS style classes used by @racketmodname[scribble/base] forms and
functions:
@itemlist[
@item{@other-doc['(lib "scribblings/scribble/demo-s1.scrbl")] shows
the default style in a single-page rendering without a search
box.}
@item{@other-doc['(lib "scribblings/scribble/demo-m1.scrbl")] shows
the default style in a multi-page rendering without a search
box.}
@item{@other-doc['(lib "scribblings/scribble/demo-s2.scrbl")] shows
the current manual style's adjustments in a single-page
rendering with a search box.}
@item{@other-doc['(lib "scribblings/scribble/demo-m2.scrbl")] shows
the current manual style's adjustments in a multi-page
rendering with a search box.}
]
The style classes:
@(css-table
[@css{maincolumn} @elem{Outer wrapper for all content in the main column.}]
[@css{main} @elem{Inner wrapper for all content in the main column, including navigation bars.}]
[@spacer @spacer]
[@css{refpara} @elem{Outer wrapper for right-hand @racket[margin-note] notes.}]
[@css{refparaleft} @elem{Outer wrapper for left-hand @racket[margin-note] notes.}]
[@css{refelem} @elem{Outer wrapper for right @racket[margin-note*] notes.}]
[@css{refelemleft} @elem{Outer wrapper for left-hand @racket[margin-note*] notes.}]
[@css{refcolumn} @elem{Middle wrapper for right-hand @racket[margin-note] and @racket[margin-note*] notes.}]
[@css{refcolumnleft} @elem{Middle wrapper for left-hand @racket[margin-note] and @racket[margin-note*] notes.}]
[@css{refcontent} @elem{Inner wrapper for @racket[margin-note] and @racket[margin-note*] notes.}]
[@spacer @spacer]
[@css{tocset} @elem{Groups table-of-contents panels: main and ``on this page.''}]
[@spacer @spacer]
[@css{tocview} @elem{Wraps the main (multi-page mode) or only (single-page mode) table-of-contents panel.}]
[@css{tocviewlist} @elem{A hierarchical layer of content in a main table-of-contents panel.}]
[@css{tocviewlisttopspace} @elem{With @css{tocviewlist} for the first layer.}]
[@css{tocviewtoggle} @elem{The always-visible name of a layer.}]
[@css{tocviewtitle} @elem{With @css{tocviewtoggle} for the first layer.}]
[@css{tocviewsublist} @elem{An item in a layer that has multiple items and more items before and after.}]
[@css{tocviewsublistonly} @elem{An item in a single-item layer.}]
[@css{tocviewsublisttop} @elem{The first item in a multi-item layer.}]
[@css{tocviewsublistbottom} @elem{The last item in a multi-item layer.}]
[@css{tocviewlink} @elem{Inner wrapper for an item in a layer when linked to a different page.}]
[@css{tocviewselflink} @elem{Inner wrapper for every item in a layer when linked to the same page.}]
[@spacer @spacer]
[@css{tocsub} @elem{Wraps the ``on this page'' (multi-page mode only) table-of-contents panel.}]
[@css{tocsubtitle} @elem{Wraps the words ``on this page''.}]
[@css{tocsublist} @elem{Inner table for the ``on this page'' panel.}]
[@css{tocsublinknumber} @elem{Number for an entry in an ``on this page'' panel.}]
[@css{tocsubseclink} @elem{Title for a @emph{section} entry in an ``on this page'' panel.}]
[@css{tocsubnonseclink} @elem{Title for a @emph{non-section} entry in an ``on this page'' panel
that has some section links.}]
[@css{tocsublink} @elem{Title for a @emph{non-section} entry in an ``on this page'' panel
that has no section links.}]
[@css{toctoplink} @elem{Top-level entry in an inline (not the panel) table of contents.}]
[@css{toclink} @elem{Nested entry in an inline (not the panel) table of contents.}]
[@spacer @spacer]
[@css{versionbox} @elem{Outer wrapper for version}]
[@css{version} @elem{Inner wrapper for version in the case of search box and/or navigation.}]
[@css{versionNoNav} @elem{Inner wrapper for version in the acse of no search box and navigation.}]
[@spacer @spacer]
[@css{SAuthorListBox} @elem{Outer wrapper for the author list.}]
[@css{SAuthorList} @elem{Inner wrapper for the author list.}]
[@css{author} @elem{Wrapper for an individual author.}]
[@spacer @spacer]
[@css{navsettop} @elem{Wraps the top navigation bar (in multi-page mode or when a search bar is present).}]
[@css{navsetbottom} @elem{Wraps the bottom navigation bar (in multi-page mode or when a search bar is present).}]
[@css{navleft} @elem{Wraps left-side elements within a navigation bar.}]
[@css{navright} @elem{Wraps right-side elements within a navigation bar.}]
[@css{nonavigation} @elem{Disabled links within a navigation bar.}]
[@css{searchform} @elem{Outer wrapper for a search box within the top navigation bar.}]
[@css{searchbox} @elem{Inner wrapper for a search box within the top navigation bar.}]
[@css{nosearchform} @elem{Takes the place of an absent search box within the top navigation bar.}]
[@spacer @spacer]
[@css{SSubSubSubSection} @elem{Deeply nested subsection (below @tt{<h5>}).}]
[@spacer @spacer]
[@css{SIntrapara} @elem{Used with @tt{<div>} instead of @tt{<p>} for a paragraph
within a @racket[compound-paragraph].}]
[@spacer @spacer]
[@css{SubFlow} @elem{For a @racket[nested-flow] with no style name: no inset.}]
[@css{SCodeFlow} @elem{For a @racket[nested-flow] with the @racket['code-inset] style name:
inset suitable for code.}]
[@css{SVInsetFlow} @elem{For a @racket[nested-flow] with the @racket['vertical-inset] style name:
add space before and after suitable for code.}]
[@css{SCentered} @elem{For a @racket[nested-flow] created by @racket[centered]: horizontally
centered.}]
[@spacer @spacer]
[@css{boxed} @elem{For a @racket[table] with the @racket['boxed] style name: as a definition box.}]
[@spacer @spacer]
[@css{compact} @elem{For an @racket[itemlist] with the @racket['compact] style name.}]
[@spacer @spacer]
[@css{techoutside} @elem{Outer wrapper for a technical-term reference.}]
[@css{techinside} @elem{Inner wrapper for a technical-term reference.}]
[@spacer @spacer]
[@css{indexlink} @elem{For an entry in the index.}]
[@spacer @spacer]
[@css{stt} @elem{Fixed-width text.}]
[@css{sroman} @elem{Serif text.}]
[@css{ssanserif} @elem{Sans serif text.}]
[@css{slant} @elem{Oblique (as opposed to italic) text.}]
[@css{Smaller} @elem{Smaller text (as created by @racket[smaller]).}]
[@css{Larger} @elem{Smaller text (as created by @racket[larger]).}]
[@css{hspace} @elem{For whitespace produced by @racket[hspace].}]
[@css{nobreak} @elem{Disable link breaks.}]
[@css{badlink} @elem{Broken cross-reference.}]
[@css{plainlink} @elem{Hyperlink without an underline.}])
In addition, the @css{SIEHidden} style class is built in to all
Scribble HTML output to hide an element on Internet Explorer 6.
@; ------------------------------------------------------------
@section[#:tag "manual-css"]{Manual CSS Style Classes}
The following renderings of @elem[#:style (style #f (list
(link-resource "demo-manual.scrbl")))]{@filepath{demo-manual.scrbl}}
demonstrate all of the CSS style classes used by
@racketmodname[scribble/manual] forms and functions in addition to the
@seclink["builtin-css"]{base style classes}.
@itemlist[
@item{@other-doc['(lib "scribblings/scribble/demo-manual-s1.scrbl")] shows
the original style in a single-page rendering without a search
box.}
@item{@other-doc['(lib "scribblings/scribble/demo-manual-m1.scrbl")] shows
the original style in a multi-page rendering without a search
box.}
@item{@other-doc['(lib "scribblings/scribble/demo-manual-s2.scrbl")] shows
the current manual style's adjustments in a single-page
rendering with a search box.}
@item{@other-doc['(lib "scribblings/scribble/demo-manual-m2.scrbl")] shows
the current manual style's adjustments in a multi-page
rendering with a search box.}
]
The style classes:
@(css-table
[@css{RktSym} @elem{Identifiers with no @racket[for-label] binding.}]
[@css{RktValLink} @elem{Identifier with @racket[for-label] binding to a variable definition.}]
[@css{RktValDef} @elem{Definition site of a variable, normally combined with @css{RktValLink}.}]
[@css{RktStxLink} @elem{Identifier with @racket[for-label] binding to a syntactic-form definition.}]
[@css{RktStxDef} @elem{Definition site of a syntactic form, normally combined with @css{RktStxLink}.}]
[@css{RktSymDef} @elem{Definition site of an identifier without binding (normally a mistake), combined with @css{RktSym}.}]
[@css{RktVar} @elem{Local variable or meta-variable.}]
[@css{RktRes} @elem{REPL result.}]
[@css{RktOut} @elem{Output written to the current output port.}]
[@css{RktErr} @elem{Output written to the current error port.}]
[@css{RktCmt} @elem{A comment in Racket code.}]
[@css{RktVal} @elem{A literal value in Racket code.}]
[@css{RktPn} @elem{Parentheses, keywords, and similar delimiters in Racket code.}]
[@css{RktRdr} @elem{Reader shorthands in Racket code, except for commas.}]
[@css{RktMeta} @elem{An unquoting comma in Racket code.}]
[@css{highlighted} @elem{Hilighlted code (via @racket[code:highlight] in @racket[racketblock], for example).}]
[@css{RktIn} @elem{Foreground for literal characters written with @racket[litchar].}]
[@css{RktInBG} @elem{Background for literal characters written with @racket[litchar].}]
[@css{RktModLink} @elem{A module name linked to the module's definition.}]
[@css{RktMod} @elem{A module name (normally @css{RktModLink}, instead).}]
[@css{RktKw} @elem{A ``keyword;'' not normally used.}]
[@css{RktOpt} @elem{Brackets for optional arguments (in function definitions).}]
[@spacer @spacer]
[@css{RktBlk} @elem{Wrapper for multi-linke Racket code blocks.}]
[@spacer @spacer]
[@css{defmodule} @elem{Module definition block.}]
[@css{RpackageSpec} @elem{Package specification within a module-definition block.}]
[@spacer @spacer]
[@css{RBoxed} @elem{Definition block; always combined with @css{boxed}.}]
[@css{together} @elem{Table within a @racket[together] grouping.}]
[@css{RBackgroundLabel} @elem{Wrapper for ``procedure,'' ``syntax,'' etc., backing in a definition box.}]
[@css{RBackgroundLabelInner} @elem{Wrapper within @css{RBackgroundLabel}.}]
[@css{RForeground} @elem{Wrapper for element to appear over a @css{RBackgroundLabel}.}]
[@css{prototype} @elem{Wrapper for a multi-line procedure-definition prototype.}]
[@css{argcontract} @elem{Wrapper for a multi-line argument contract and default value.}]
[@css{specgrammar} @elem{Wrapper for a grammar with a syntactic-form definition box.}]
[@css{inherited} @elem{Wrapper for a margin ``inherited methods'' table.}]
[@css{inheritedlbl} @elem{Wrapper for ``Inherited methods:'' and ``from'' labels.}]
[@spacer @spacer]
[@css{leftindent} @elem{Left-indented block, such as form @racket[specsubform].}]
[@css{insetpara} @elem{Inset block.}]
[@spacer @spacer]
[@css{Rfilebox} @elem{Wrapper for a file box (via @racket[filebox]),}]
[@css{Rfiletitle} @elem{Outer wrapper for a file box title.}]
[@css{Rfilename} @elem{Inner wrapper for a file box title.}]
[@css{Rfilecontent} @elem{Wrapper for file box content.}]
[@spacer @spacer]
[@css{SHistory} @elem{Wrapper for @racket[history] paragraphs.}]
[@spacer @spacer]
[@css{RBibliography} @elem{Wrapper for a @racket[bibliography] section.}])
@; ------------------------------------------------------------
@section[#:tag "builtin-latex"]{Base Latex Macros}
The @filepath{scribble.tex} Latex configuration includes several
macros and environments that you can redefine to adjust the output
style:
@itemlist[
@item{@ltxd[0]{preDoc} --- called before the document content; the
default does nothing, while the @racketmodname[scribble/manual]
configuration enabled @ltx{sloppy}.}
@item{@ltxd[0]{postDoc} --- called after the document content; the
default does nothing.}
@item{@ltxd[0]{sectionNewpage} --- called before each top-level
section starts; the default does nothing, while the
@racketmodname[scribble/manual] configuration uses
@ltx{newpage} to start each chapter on a new page.}
@item{@ltxd[3]{SecRefLocal} --- the first argument is a Latex label,
the second argument is a section number, and the third argument
is a section title. This macro is used by @racket[secref] to
reference a section (other than a document or top-level section
within a document) that has a number and that is local to the
current document. The default expands to @ltx{SecRef}, passing
along just the second and third arguments (so that the label is
ignored).}
@item{@ltxd[2]{SecRef} --- like @ltx{SecRefLocal}, but used when the
referenced section is in a different document, so that no label
is available. The default shows ``section'' followed by the
section number (ignoring the title). The
@racketmodname[scribble/manual] redefinition of this macro
shows ``§'', the section number, and the title in quotes.}
@item{@ltxd[3]{ChapRefLocal} and @ltxd[2]{ChapRef} --- like
@ltx{SecRefLocal} and @ltx{SecRef}, but for a top-level section
within a document. The default implementation defers to
@ltx{SecRefLocal} or @ltx{SecRef}.}
@item{@ltxd[3]{PartRefLocal} and @ltxd[2]{PartRef} --- like
@ltx{SecRefLocal} and @ltx{SecRef}, but for a top-level section
within a document whose part has the @racket['grouper] style
property. The default @ltx{PartRef} shows ``part'' followed by
the section number (ignoring the title).}
@item{@ltxd[3]{BookRefLocal} and @ltxd[2]{BookRef} --- like
@ltx{SecRefLocal} and @ltx{SecRef}, but for a document (as
opposed to a section within the document). The default
@ltx{BookRef} implementation shows the title in italic.}
@item{@ltxd[3]{SecRefLocalUC} and @ltxd[2]{SecRefUC} --- like
@ltx{SecRefLocal} and @ltx{SecRef}, but for @racket[Secref].
The default @ltx{SecRefUC} shows ``Section'' followed by the
section number.}
@item{@ltxd[3]{ChapRefLocalUC} and @ltxd[2]{ChapRefUC} --- like
@ltx{ChapRefLocal} and @ltx{ChapRef}, but for
@racket[Secref]. The default @ltx{ChapRefUC}implementation
defers to @ltx{SecRefUC}.}
@item{@ltxd[3]{PartRefLocalUC} and @ltxd[2]{PartRefUC} --- like
@ltx{PartRefLocal} and @ltx{PartRef}, but for @racket[Secref].
The default @ltx{PartRefUC} shows ``Part'' followed by the
section number.}
@item{@ltxd[3]{BookRefLocalUC} and @ltxd[2]{BookRefUC} --- like
@ltx{BookRefLocal} and @ltx{BookRef}, but for @racket[Secref].
The default @ltx{BookRefUC} defers to @ltx{BookRef}.}
@item{@ltxd[2]{SecRefLocalUN}, @ltxd[1]{SecRefUCUN},
@ltxd[2]{SecRefLocalUCUN}, @ltxd[1]{SecRefUN},
@ltxd[2]{PartRefLocalUN}, @ltxd[1]{PartRefUN},
@ltxd[2]{PartRefLocalUCUN}, @ltxd[1]{PartRefUCUN},
@ltxd[2]{BookRefLocalUN}, @ltxd[1]{BookRefUN},
@ltxd[2]{BookRefLocalUCUN}, @ltxd[1]{BookRefUCUN},
@ltxd[2]{ChapRefLocalUN}, @ltxd[1]{ChapRefUN},
@ltxd[2]{ChapRefLocalUCUN}, and @ltxd[1]{ChapRefUCUN} --- like
@ltx{SecRefLocal}, etc., but in the case that a
section/part/chapter number is unavailable. The default
implementation of @ltx{BookRefUN} uses @ltx{BookRef} with an
empty first argument. The default @ltx{SecRefLocalUN} expands
to its second argument in quotes followed by ``on page'' as a
@ltx{pageref} using the first argument, while the default
@ltx{SecRefUN} expands to its only argument in quotes. The
default @ltx{PartRef} and @ltx{ChapRef} variants expand to the
corresponding @ltx{SecRef} variant.}
@item{@ltxd[2]{Ssection}, @ltxd[2]{Ssubsection},
@ltxd[2]{Ssubsubsection}, @ltxd[2]{Ssubsubsubsection},
@ltxd[2]{Ssubsubsubsubsection} --- for a top-level section, a
second-level section, etc., where the last variant is used for
all sections that are deeper than four levels. The first
argument corresponds to the optional argument to
@ltx{section}, which is used for the table of contents.}
@item{@ltxd[1]{Ssectionstar}, @ltxd[1]{Ssubsectionstar},
@ltxd[1]{Ssubsubsectionstar}, @ltxd[1]{Ssubsubsubsectionstar},
@ltxd[1]{Ssubsubsubsubsectionstar} --- like @ltx{Ssection},
etc., but for unnumbered sections that are omitted from the
table of contents.}
@item{@ltxd[2]{Ssectionstarx}, @ltxd[1]{Ssubsectionstarx},
@ltxd[2]{Ssubsubsectionstarx},
@ltxd[2]{Ssubsubsubsectionstarx},
@ltxd[2]{Ssubsubsubsubsectionstarx} --- like @ltx{Ssection},
etc., but for unnumbered sections (that nevertheless appear in
the table of contents).}
@item{@ltxd[0]{Sincsection}, @ltxd[0]{Sincsubsection},
@ltxd[0]{Sincsubsubsection}, @ltxd[0]{Sincsubsubsubsection},
@ltxd[0]{Sincsubsubsubsubsection} --- increments the section
counter.}
@item{@ltxd[2]{Spart}, @ltxd[1]{Spartstar}, @ltxd[2]{Spartstarx},
@ltxd[0]{Sincpart} --- like the section commands, but used for
in place of @ltxd[2]{Ssection}, @ltxd[1]{Ssectionstar}, @|etc|
for a part with the @racket['grouper] style property.}
@item{@ltxe{SInsetFlow} environment --- for a @racket[nested-flow]
with the @racket['inset] style name.}
@item{@ltxe{SCodeFlow} environment --- for a @racket[nested-flow]
with the @racket['code-inset] style name.}
@item{@ltxe{SVInsetFlow} environment --- for a @racket[nested-flow]
with the @racket['vertical-inset] style name.}
@item{@ltxd[1]{SCodeBox}, @ltxd[1]{SVInsetBox} --- for a
@racket[nested-flow] with the @racket['code-inset] or
@racket['vertical-inset] style name, respectively, and as the
content of a table cell. The content is installed into a TeX
box using @tt{\setbox1}.}
]
@; ------------------------------------------------------------
@section[#:tag "latex-prefix"]{Latex Prefix Support}
@defmodule[scribble/latex-prefix]{Provides a string that is useful for
constructing a Latex document prefix.}
@defthing[unicode-encoding-packages string?]{
A string containing Latex code that is useful after a
@tt{\documentclass} declaration to make Latex work with Unicode
characters.}

1801
scribble-doc/scribblings/scribble/core.scrbl
View File

File diff suppressed because it is too large Load Diff

228
scribble-doc/scribblings/scribble/decode.scrbl
View File

@ -1,228 +0,0 @@
#lang scribble/doc
@(require scribble/manual "utils.rkt")
@title[#:tag "decode"]{Decoding Text}
@defmodule[scribble/decode]{The @racketmodname[scribble/decode]
library helps you write document content in a natural way---more like
plain text, except for @litchar["@"] escapes. Roughly, it processes a
stream of strings to produces instances of the
@racketmodname[scribble/struct] datatypes (see @secref["struct"]).}
At the @tech{flow} level, decoding recognizes a blank line as a
@tech{paragraph} separator. Blocks and paragraphs without blank lines
in between are collected into a @tech{compound paragraph}.
@elemtag['(decode "rules")]{At} the @tech{content} level, decoding
makes just a few special text conversions:
@itemize[
@item{@litchar{---}: converted to @racket['mdash]}
@item{@litchar{--}: converted to @racket['ndash]}
@item{@litchar{``}: converted to @racket['ldquo], which is fancy open quotes: ``}
@item{@litchar{''}: converted to @racket['rdquo], which is fancy closing quotes: ''}
@item{@litchar{'}: converted to @racket['rsquo], which is a fancy apostrophe: '}
@item{@litchar{`}: converted to @racket['lsquo], which is a fancy quote: `}
]
Some functions @deftech{decode} a sequence of @racket[_pre-flow] or
@racket[_pre-content] arguments using @racket[decode-flow] or
@racket[decode-content], respectively. For example, the @racket[bold]
function accepts any number of @racket[_pre-content] arguments, so
that in
@verbatim[#:indent 2]|{@bold{``apple''}}|
the @litchar{``apple''} argument is decoded to use fancy quotes, and
then it is bolded.
@defproc[(pre-content? [v any/c]) boolean?]{
Returns @racket[#t] if @racket[v] is a @deftech{pre-content} value: a
string or other non-list @tech{content}, a list of @tech{pre-content} values, or a @racket[splice]
containing a list of @tech{pre-content} values; otherwise returns
@racket[#f].
Pre-content is decoded into @tech{content} by functions like
@racket[decode-content] and @racket[decode-paragraph].}
@defproc[(pre-flow? [v any/c]) boolean?]{
Returns @racket[#t] if @racket[v] is a @deftech{pre-flow} value: a
string or other non-list @tech{content}, a @racket[block],
@|void-const|, a list of @tech{pre-flow} values, or a @racket[splice] containing a list of
@tech{pre-flow} values; otherwise returns @racket[#f].
Pre-flow is decoded into a @tech{flow} (i.e., a list of @tech{blocks})
by functions like @racket[decode-flow].}
@defproc[(pre-part? [v any/c]) boolean?]{
Returns @racket[#t] if @racket[v] is a @deftech{pre-part} value: a
string or other non-list @tech{content}, a @tech{block}, a
@racket[part], a @racket[title-decl], a @racket[part-start], a
@racket[part-index-decl], a @racket[part-collect-decl], a
@racket[part-tag-decl], @|void-const|, a list of @tech{pre-part} values, or a @racket[splice] containing
a list of @tech{pre-part} values; otherwise returns @racket[#f].
A pre-part sequence is decoded into a @racket[part] by functions like
@racket[decode] and @racket[decode-part].}
@defproc[(decode [lst (listof pre-part?)]) part?]{
Decodes a document, producing a part. In @racket[lst], lists and instances of
@racket[splice] are inlined into the list, and @|void-const|s are dropped. An instance of
@racket[title-decl] supplies the title for the part, plus tag, style
and version information. Instances of @racket[part-index-decl] (that
precede any sub-part) add index entries that point to the
section. Instances of @racket[part-collect-decl] add elements to the
part that are used only during the @techlink{collect pass}. Instances
of @racket[part-tag-decl] add hyperlink tags to the section
title. Instances of @racket[part-start] at level 0 trigger sub-part
parsing. Instances of @racket[section] trigger are used as-is as
subsections, and instances of @racket[paragraph] and other
flow-element datatypes are used as-is in the enclosing flow.
Portions of @racket[lst] are within a part are decoded using
@racket[decode-flow].}
@defproc[(decode-part [lst (listof pre-part?)]
[tags (listof string?)]
[title (or/c #f list?)]
[depth exact-nonnegative-integer?])
part?]{
Like @racket[decode], but given a list of tag string for the part, a
title (if @racket[#f], then a @racket[title-decl] instance is used if
found), and a depth for @racket[part-start]s to trigger sub-part
parsing.
}
@defproc[(decode-flow [lst (listof pre-flow?)]) (listof block?)]{
Decodes a flow. In @racket[lst], lists and instances of
@racket[splice] are inlined into the list. A sequence of two or more
newlines separated only by whitespace is parsed as a
compound-paragraph separator.
Portions of @racket[lst] are within a compound paragraph are decoded using
@racket[decode-compound-paragraph].}
@defproc[(decode-compound-paragraph [lst (listof pre-flow?)]) block?]{
Decodes a compound paragraph. In @racket[lst], lists and instances of
@racket[splice] are inlined into the list. Instances of
@racket[paragraph] and other @tech{block} datatypes are used as-is in
the result. If the compound paragraph contains a single block, the
block is returned without a @racket[compound-paragraph] wrapper.
Portions of @racket[lst] that are separated by @tech{block}s are
decoded using @racket[decode-content].}
@defproc[(decode-paragraph [lst (listof pre-content?)]) paragraph?]{
Decodes a paragraph using @racket[decode-content] to decode
@racket[lst] as the paragraph's content.}
@defproc[(decode-content [lst (listof pre-content?)]) list?]{
Decodes @tech{content}. Elements at the start of the list that are
whitespace (according to @racket[whitespace?]) are dropped.
@margin-note*{Dropping whitespace in nested lists and splices was a poor
implementation choice that is left in place for compatibility. To protect
against it, you can exploit the similarly unfortunate fact that an empty
list does not count as whitespace.}
Lists and splices in @racket[lst] are
flattened into the list, similarly dropping leading whitespace.
Plain strings are @elemref['(decode
"rules")]{decoded}; non-string, non-list @tech{content} is included in
the result as-is.}
@defproc[(decode-elements [lst (listof pre-content?)]) list?]{
An alias for @racket[decode-content].}
@defproc[(decode-string [s string?]) (listof content?)]{
@elemref['(decode "rules")]{Decodes} a single string to produce
@tech{content}.}
@defproc[(whitespace? [v any/c]) boolean?]{
Returns @racket[#t] if @racket[v] is a string that contains only whitespace, @racket[#f]
otherwise.}
@defstruct[title-decl ([tag-prefix (or/c #f string?)]
[tags (listof string?)]
[version (or/c string? #f)]
[style style?]
[content content?])]{
See @racket[decode] and @racket[decode-part]. The @racket[tag-prefix]
and @racketidfont{style} fields are propagated to the resulting
@racket[part]. If the @racketidfont{version} field is not @racket[#f],
it is propagated as a @racket[document-version] style property on the
@racket[part].}
@defstruct[part-start ([depth integer?]
[tag-prefix (or/c #f string?)]
[tags (listof string?)]
[style style?]
[title content?])]{
Like @racket[title-decl], but for a sub-part. See @racket[decode] and
@racket[decode-part].}
@defstruct[part-index-decl ([plain-seq (listof string?)]
[entry-seq list?])]{
See @racket[decode]. The two fields are as for @racket[index-element].}
@defstruct[part-collect-decl ([element (or/c element? part-relative-element?)])]{
See @racket[decode].}
@defstruct[part-tag-decl ([tag tag?])]{
See @racket[decode].}
@defstruct[splice ([run list?])]{
See @racket[decode], @racket[decode-part], and @racket[decode-flow].}
@defproc[(spliceof [ctc flat-contract?]) flat-contract?]{
Produces a contract for a @racket[splice] instance whose
@racketidfont{run} elements satisfy @racket[ctc].}
@defproc[(clean-up-index-string [str string?]) string?]{
Trims leading and trailing whitespace, and converts non-empty
sequences of whitespace to a single space character.}

23
scribble-doc/scribblings/scribble/demo-class.scrbl
View File

@ -1,23 +0,0 @@
#lang scribble/base
@(require scribble/manual
(for-label racket/base
racket/class
racket/contract/base
racket/draw))
@(define css tt)
@defclass/title[#:link-target? #f bitmap-dc% object% (dc<%>)]{
In multi-page mode, this class definition gets its own page, and
there's an ``inherited methods'' table in the margin. The table has
style class @css{inherited}, and the words ``inherited methods:'' and
``from'' have style class @css{inheritedlbl}.
@defmethod[#:link-target? #f (set-bitmap [bm any/c]) any]{
A method example; nothing new here, but note how the defined
identifier is not at the start of the box.}
}

10
scribble-doc/scribblings/scribble/demo-m1.scrbl
View File

@ -1,10 +0,0 @@
#lang racket/base
(require "demo.scrbl"
scribble/core)
(define renamed-doc
(struct-copy part doc
[title-content
(cons "M1 " (part-title-content doc))]))
(provide (rename-out [renamed-doc doc]))

12
scribble-doc/scribblings/scribble/demo-m2.scrbl
View File

@ -1,12 +0,0 @@
#lang racket/base
(require "demo.scrbl"
scribble/core
scribble/manual)
(define renamed-doc
(struct-copy part doc
[style manual-doc-style]
[title-content
(cons "M2 " (part-title-content doc))]))
(provide (rename-out [renamed-doc doc]))

10
scribble-doc/scribblings/scribble/demo-manual-m1.scrbl
View File

@ -1,10 +0,0 @@
#lang racket/base
(require "demo-manual.scrbl"
scribble/core)
(define renamed-doc
(struct-copy part doc
[title-content
(cons "M1 " (part-title-content doc))]))
(provide (rename-out [renamed-doc doc]))

12
scribble-doc/scribblings/scribble/demo-manual-m2.scrbl
View File

@ -1,12 +0,0 @@
#lang racket/base
(require "demo-manual.scrbl"
scribble/core
scribble/manual)
(define renamed-doc
(struct-copy part doc
[style manual-doc-style]
[title-content
(cons "M2 " (part-title-content doc))]))
(provide (rename-out [renamed-doc doc]))

10
scribble-doc/scribblings/scribble/demo-manual-s1.scrbl
View File

@ -1,10 +0,0 @@
#lang racket/base
(require "demo-manual.scrbl"
scribble/core)
(define renamed-doc
(struct-copy part doc
[title-content
(cons "S1 " (part-title-content doc))]))
(provide (rename-out [renamed-doc doc]))

12
scribble-doc/scribblings/scribble/demo-manual-s2.scrbl
View File

@ -1,12 +0,0 @@
#lang racket/base
(require "demo-manual.scrbl"
scribble/core
scribble/manual)
(define renamed-doc
(struct-copy part doc
[style manual-doc-style]
[title-content
(cons "S2 " (part-title-content doc))]))
(provide (rename-out [renamed-doc doc]))

203
scribble-doc/scribblings/scribble/demo-manual.scrbl
View File

@ -1,203 +0,0 @@
#lang scribble/base
@(require scribble/manual
scribble/eval
(for-syntax racket/base)
(for-label racket/base
racket/contract/base
scribble/manual))
@(define css tt)
@(define-syntax (opt-example stx)
;; A #\? 'paren-shape value triggers RktOpt:
#`@racket[#,(syntax-property #'(in-example) 'paren-shape '#\?)])
@title{Manual All-Styles Document}
@table-of-contents[]
@section{Code Styles}
@itemlist[
@item{@css{RktSym} (identifier without @racket[for-label] binding):
@racket[unbound] or @racketidfont{example}}
@item{@css{RktValLink} (link to variable form): @racket[cons]}
@item{@css{RktValDef} (definition of variable, normally combined with @css{RktValLink}):
@racket[list] in
@defproc[#:link-target? #f (list) any/c]
@defthing[#:link-target? #f list any/c]}
@item{@css{RktStxLink} (link to syntactic form): @racket[lambda]}
@item{@css{RktStxDef} (definition of syntactic form, normally combined with @css{RktStxLink}):
@racket[lambda] in
@defform[#:link-target? #f (lambda ...)]}
@item{@css{RktSymDef} (definition without binding, normally a mistake, combined with @css{RktSym}):
@racket[unbound-identifier] in
@defform[#:link-target? #f (unbound-identifier)]}
@item{@css{RktVar} (local variable or meta-variable): @racket[_variable] or @racketvarfont{example}}
@item{@css{RktRes} (REPL result): @racketresult['(1 2 3)] or @racketresultfont{example}}
@item{@css{RktOut} (as written to the current output port): @racketoutput{example}}
@item{@css{RktErr} (errors): @racketerror{example} or the error message in
@interaction[(eval:error (+ 1 'a))]}
@item{@css{RktCmt} (comments): @racketcommentfont{example} or
@racketblock[(code:comment "comment")]}
@item{@css{RktVal} (values): @racket['(1 2 3)] or @racketvalfont{example}}
@item{@css{highlighted} (highlight via background): @racket[(not-this (code:hilite example) nor-this)]}
@item{@css{RktIn} on a @css{RktInBG}: @litchar{example}}
@item{@css{RktPn} (parentheses, etc.): @racket[([{}])] or @racketparenfont{example}}
@item{@css{RktRdr} (reader shorthands): non-parentheses in @racket[(#`() ,@())]}
@item{@css{RktMeta} (the @racket[unquote] comma):
@racket[,1] or @racketmetafont{example} or ``#reader'' below.
@defmodule[@schemeidfont{module} #:module-paths (racket/base) #:reader #:no-declare #:link-target? #f]}
@item{@css{RktMod} (module name; normally @css{RktModLink} instead): @racketmodfont{example}}
@item{@css{RktModLink} (a linked module reference): @racketmodname[racket/base]}
@item{@css{RktOpt} (option-argument brackets): brackets in @opt-example[]}
@item{@css{RktKw} (not normally used): @racketkeywordfont{example}}
]
The @css{RktBlk} style class is used for a table of multiple lines (more
than 1) of Racket code:
@racketblock[
(define x (+ 1 2))
(+ x 3)
]
@section{Definition Blocks}
@defmodule[racket/base #:link-target? #f]
The module-declaration box above is in a @css{defmodule} table. The
package-specification part is in an @css{RpackageSpec} wrapper.
The definitions below are marked so that they are not link targets. If
they were link targets, the table-of-contents panel on the left would
have entries for them.
@defproc[#:link-target? #f (cons [really-long-name-for-the-first-argument
any/c]
[really-long-name-for-the-second-argument
(or/c any/c
any/c)])
pair?]{
This definition box starts with a @css{SVInsetFlow} wrapper, which is a
@racketmodname[scribble/base] style class for the
@racket['vertical-inset] style name on a block; it should give the
block suitable vertical space before and after.
The next layer is a @css{boxed} plus @css{RBoxed} table. The @css{boxed}
style class is from @racketmodname[scribble/base] and the
@racket['boxed] style name on a table. The @css{RBoxed} style class is
from the @racket[scribble/manual] layer. Both @css{boxed} and @css{RBoxed}
are used for all definition boxes by @racket[scribble/manual] forms.
The initial content of the table includes a @css{SubFlow} (a
@racket[scribble/base] style class for non-indented flow) to combine
blocks for the background label with the first line of the table. The
background label ``procedure'' has an @css{RBackgroundLabel} outer
wrapper, which makes the label float right. (The wrapper also has the
@css{SIEHidden} style class, which built-in for all Scribble HTML output
and makes the label hidden on Internet Explorer 6 and earlier.) The
background label has an @css{RBackgroundLabelInner} inner wrapper, which
makes the label suitably faint. The content part of the first line is
wrapped in @css{RForeground}, which ensures that it is in front of the
background label.
In a procedure definition box:
@itemlist[
@item{When the initial ``prototype'' call in the definition box spans
multiple lines, the table that contains the call has the
@css{prototype} style class in addition to @css{RForeground}.}
@item{When the contract or default value for an argument spans
multiple lines, then the contract, the ``='' for a value (if
any), and value (if any) are wrapped in an table with the
@css{argcontract} style class.}
]
Finally, the definition box and all of the associated explanation text
are wrapped in @css{SIntrapara} blocks and grouped into a single
@tt{<p>}.}
@defform[#:link-target? #f
(lambda ...)
#:grammar ([example good
bad])]
When a syntactic-from specification has a grammar, the grammar is in a
table with the @css{specgrammar} style class.
Since no explanation flow is attached to the above @racket[defform] use,
there's no @css{SIntrapara} block around the table (just a @tt{<p>}).
@deftogether[(
@defproc[#:link-target? #f (cons [a any/c] [d any/c]) pair?]
@defform[#:link-target? #f (lambda ...)]
)]{
Putting definitions together with @racket[deftogether] converts the
@css{RBoxed} and @css{boxed} tables that would be generated for the
individual definitions into tables with the @css{together} style
class. The tables are then combined as rows in a new table with the
@css{RBoxed} and @css{boxed} style classes.}
A @racket[defsubform], @racket[specsubform], etc., such as
@specsubform[(lambda ...)]
is indented though a wrapper with a @css{leftindent} style class.
@include-section["demo-class.scrbl"]
@section{Miscellaneous}
In @racket[filebox] rendering,
@(filebox "example.rkt" "This is a file box")
a @css{Rfilebox} wrapper surrounds the file name in a @css{Rfiletitle}
outer wrapper and an @css{Rfilename} inner wrapper, plus the file
content in an @css{Rfilecontent} wrapper.
@inset-flow{The @racket[inset-flow] form generates a
@racket[nested-flow] with style class @css{insetpara}.}
@history[#:changed "1.0" @elem{History paragraphs have the @css{SHistory} style class.}]
@section{Bibliography}
The bibliography table for the citation @cite["Example"] as the
@css{RBibliography} style class.
@bibliography[(bib-entry #:key "Example" #:title "Example bibliography entry")]

10
scribble-doc/scribblings/scribble/demo-s1.scrbl
View File

@ -1,10 +0,0 @@
#lang racket/base
(require "demo.scrbl"
scribble/core)
(define renamed-doc
(struct-copy part doc
[title-content
(cons "S1 " (part-title-content doc))]))
(provide (rename-out [renamed-doc doc]))

12
scribble-doc/scribblings/scribble/demo-s2.scrbl
View File

@ -1,12 +0,0 @@
#lang racket/base
(require "demo.scrbl"
scribble/core
scribble/manual)
(define renamed-doc
(struct-copy part doc
[style manual-doc-style]
[title-content
(cons "S2 " (part-title-content doc))]))
(provide (rename-out [renamed-doc doc]))

324
scribble-doc/scribblings/scribble/demo.scrbl
View File

@ -1,324 +0,0 @@
#lang scribble/base
@(require scribble/core
scribble/manual)
@title[#:tag "top" #:version "1.0" #:style 'toc-hidden]{All-Styles Document, Title in ``H2''}
@author["Jack" "Jill"]
All of this content is within ``maincolumn'', then ``main''.
@"\U2192" The version on the top left of this page is in
``versionbox'' and then either span ``versionNoNav'' (no navigation
bar, as for single-page rendering) or ``version'' (with navigation
bar, as for multi-page rendering).
@"\U2192" The author on the top left of this page is in
``SAuthorListBox'', then ``SAuthorList'', and then a span ``author'',
where @tt{<br/>} separates multiple authors.
@"\U2190" The table-of-contents panels are both in a table ``tocset'':
@margin-note{This note is in ``refpara'', then ``refcolumn'', then
``refcontent''.}
@itemlist[
@item{The top panel is in ``tocview''.
The top panel can have multiple layers of the hierarchy. For a
single-page rendering, only one layer is present. For an
example of multiple layers when rendering this document to
multiple pages, go to @secref["deepest"].
Each layer is in a ``tocviewlist'' that also has the class
``tocviewlisttopspace'' in the case of the first layer. The
always-visible name of a layer is in a span ``tocviewtoggle'',
but that span is also in a ``tocviewtitle'' in the case of the
first layer. Each item under the title is in a
``tocviewsublist'' or a variant: ``tocviewsublistonly'' if only
a single item is present, ``tocviewsublistfirst'' for the first
item of multi, ``tocviewsublistlast'' for the last item of
multiple. Then, each item is in a span ``tocviewlink''.
Each section link in the panel is a span ``tocviewlink'' or a
span ``tocviewselflink'' if the link corresponds to the current
page or on the path to the current page.}
@item{A bottom panel is visible here only for a single-page
rendering. See its description in @secref["h3"].}
]
@margin-note[#:left? #t]{This note is in ``refparaleft'', then
``refcolumnleft'', then ``refcontent''.}
Table of contents uses ``toptoclink'' for the top layer, and
``toclink'' for nested levels:
@table-of-contents[]
@margin-note*{This note is in ``refelem'', then ``refcolumn'', then
``refcontent''.}
@margin-note*[#:left? #t]{This note is in ``refelemleft'', then
``refcolumnleft'', then ``refcontent''.}
@; ======================================================================
@section[#:tag "h3"]{Section in ``H3''}
@"\U2190" For either single-page or multi-page rendering, the
table-of-contents column here has two panels. The top panel is
described in the @seclink["h3"]{starting prose}. For the bottom panel:
@itemlist[
@item{The bottom panel is in a ``tocsub''. For a multi-page
rendering, the on-this-page title is in ``tocsubtitle''. The
rest is always in a table ``tocsublist''. For each entry, the
number part is in a span ``tocsublinknumber'', and the title
part in a span, one of the following: ``tocsubseclink'' if the
link represents a (sub)section, ``tocnonseclink'' if the link is
not a (sub)section but there are (sub)sections in the list (and
there is an example target in this section), or ``tocsublink''
if no links represent a (sub)section (see
@secref["all-non-sec"]).}
]
When a part that corresponds to a page has a @racket['no-toc] style,
the top panel of the table-of-contents column is missing and the
bottom panel is in a ``tocview'' instead of ``tocsub''. See
@secref["no-toc"].
Here is the target for the
@toc-target-element[#f @elem{``tocnonseclink''} `(demo (prefixable "non-sec"))]
link.
@subsection[#:style 'toc]{Subsection in ``H4''}
@local-table-of-contents[]
@subsubsection[#:tag "deepest"]{Subsubsection in ``H5''}
@"\U2190" This page has no on-this-page panel in a multi-page
rendering, because there are no numbered subsections, but it has three
levels shown in the table-of-contents panel.
@subsubsub*section{``SSubSubSubSection''}
@subsection{Second Subsection in ``H4''}
@; ======================================================================
@section[#:tag "no-toc" #:style 'no-toc]{Suppressed ToC Panel}
In multi-page rendering, this page has no gobal table-of-contents
panel, because it is suppressed with @racket['no-toc].
@subsection{Subsection}
@subsection{Another Subsection}
@; ======================================================================
@section[#:tag "all-non-sec"]{Non-Section On-This-Page Links}
This section has only non-section targets in the on-this-page
panel of a multi-page rendering.
Here is the target for the
@toc-target-element[#f @elem{``tocsublink'' 1} `(demo (prefixable "non-sec 1"))]
link.
Here is the target for the
@toc-target-element[#f @elem{``tocsublink'' 2} `(demo (prefixable "non-sec 2"))]
link.
Here is the target for the @as-index{``indexlink''} link in the
@seclink["doc-index"]{index} (where ``indexlink'' is used for the
index entry and not here).
@; ======================================================================
@section{Element Styles}
Some spans:
@itemlist[
@item{@tt{``stt''}}
@item{@elem[#:style 'roman]{``sroman''}}
@item{@elem[#:style "slant"]{``slant''}}
@item{@elem[#:style 'sf]{``ssanserif''}}
@item{@smaller{``Smaller''}}
@item{@larger{``Larger''}}
@item{``hspace'' is used for forced @hspace[3] space}
@item{``url'' is used for URLs: @url{http://racket-lang.org}}
@item{@elem[#:style 'no-break]{``nobreak'', which is used to prevent
line breaks anywhere in the element so that the element may run too
far right}}
@item{@italic{italic} directly sets @tt{font-style} to @tt{italic}}
@item{@bold{bold} directly sets @tt{font-weight} to @tt{bold}}
@item{@elem[#:style 'superscript]{superscript} directly sets
@tt{vertical-align} to @tt{super} and @tt{font-size} to @tt{80%}.}
@item{@elem[#:style 'subscript]{subscript} directly sets
@tt{vertical-align} to @tt{sub} and @tt{font-size} to @tt{80%}.}
]
Link spans:
@itemlist[
@item{@elemref[#:underline? #f '(prefixable "plain-target")]{``plainlink''}
hyperlink to @elemtag['(prefixable "plain-target")]{here}}
@item{@deftech{technical term} definitions are simply italicized by default}
@item{@tech{technical term} references are in ``techoutside'', then ``techinside''}
]
@; ======================================================================
@section{Block Styles}
@nested{This paragraph is in a ``SubFlow'' @tt{<blockquote>}.}
@nested[#:style 'inset]{This paragraph is in a plain @tt{<blockquote>}.}
@nested[#:style 'code-inset]{This paragraph is in a ``SCodeFlow''
@tt{<blockquote>}.}
@nested[#:style 'vertical-inset]{This paragraph is in a
``SVInsetFlow'' @tt{<blockquote>}. This style is useful when space is
not normally included between blocks.}
@centered{This paragraph is in a ``SCentered'' @tt{<blockquote>}.}
@tabular[#:style 'boxed (list (list @t{A ``boxed'' table.}))]
@; ======================================================================
@section{Enumerations}
This one is unordered, so it uses @tt{<ul>}:
@itemlist[
@item{six}
@item{half-dozen}
]
This one is ordered, so it uses @tt{<ol>}:
@itemlist[#:style 'ordered
@item{First}
@item{Second
@itemlist[#:style 'ordered
@item{Second, first half}
@item{Second, second half
@itemlist[#:style 'ordered
@item{First half of that}
@item{Second half of that
@itemlist[#:style 'ordered
@item{Thin-slice start}
@item{Thin-sliced end}
]}
]}
]}
@item{Third}
]
This one is ``compact'':
@itemlist[ #:style 'compact
@item{six}
@item{half-dozen}
]
This paragraph follows the enumeration above.
@; ======================================================================
@section{Paragraph Spacing}
This sentence is a paragraph all by itself.
@t{This sentence is a paragraph.}
@t{This sentence is also a paragraph, but it is connected to the
previous paragraph as a compound paragraph by virtue of having no
paragraph-breaking space before it, and each paragraph is in a
``SIntraPara'' @tt{<div>} instead of a @tt{<p>}.}
This sentence is a paragraph, as is each of A1, B1, A2, B2, A3, B3a,
and B2a in the following table, but B3a and B2a form a compound paragraph.
@;
@tabular[(list (list "A1"
"B1")
(list "A2"
"B2")
(list "A3"
@compound-paragraph[plain (list @t{B3a} @t{B3b})]))]
@;
This sentence is a paragraph, and with the preceding table and
paragraph forms a compound paragraph.
@nested{
@t{This is a first paragraph in a @tt{<blockquote>}.}
@t{This is a second paragraph in a @tt{<blockquote>}.}
}
@; ======================================================================
@section{Navigation Bars}
For multi-page rendering, this page will have a navigation bar at the
top and bottom. The bars are within ``maincolumn'' and ``main''.
The tap bar is in ``navsettop'', and the bottom one is in
``navsetbottom''. Within those divs, ``navsetleft'' wraps content to
be left-aligned and ``navsetright'' wraps content to be right-aligned.
Links that are disabled (such as a next-page link on the last page)
are each in a span ``nonavigation''.
When a search box is included, then it is in ``searchform'' and then
``searchbox''. If no search box is included, then a ``nosearchform''
@tt{div} is used.
Finally, and not part of the nagivation bar, the bottom nagivation bar
is followed by a @tt{div} with the name
``contextindicator''. JavaScript code attached to the page copies the
@tt{ctxtname} query argument, if any, to the @tt{div} and makes it
visible.
@; ======================================================================
@index-section[]

117
scribble-doc/scribblings/scribble/doclang.scrbl
View File

@ -1,117 +0,0 @@
#lang scribble/manual
@(require "utils.rkt")
@title[#:tag "doclang"]{Document Language}
@defmodulelang[scribble/doclang2]{The @racketmodname[scribble/doclang2]
language provides everything from @racket[racket/base], except that it
replaces the @racket[#%module-begin] form.
The @racketmodname[scribble/doclang2] @racket[#%module-begin]
essentially packages the body of the module into a call to
@racket[decode], binds the result to @racket[doc], and exports
@racket[doc].
Any module-level form other than an expression (e.g., a
@racket[require] or @racket[define]) remains at the top level, and
the @racket[doc] binding is put at the end of the module. As usual, a
module-top-level @racket[begin] slices into the module top level.
For example:
@codeblock|{
#lang racket
(module example scribble/doclang2
"hello world, this is"
" an example document")
(require 'example)
doc
}|
The behavior of @racketmodname[scribble/doclang2] can be customized by
providing @racket[#:id], @racket[#:post-process], and @racket[#:exprs]
arguments at the very beginning of the module.
@itemize[
@item{@racket[#:id] names the top-level documentation binding. By default, this
is @racket[doc].}
@item{@racket[#:post-process] processes the body of the module after
@racket[decode]. By default, this is @racket[values].}
@item{@racket[#:exprs] prepends an additional sequence of expressions to the
beginning of the module's body. By default, this is the empty sequence
@racket[()].}
]
This example explicitly uses the defaults for all three keywords:
@codeblock|{
#lang racket
(module example scribble/doclang2
#:id doc
#:post-process values
#:exprs ()
"hello world, this is an example document")
(require 'example)
doc
}|
The next toy example uses a different name for the documentation binding, and
also adds an additional binding with a count of the parts in the document:
@codeblock|{
#lang racket
(module example scribble/doclang2
#:id documentation
#:post-process (lambda (decoded-doc)
(set! number-of-parts (length (part-parts decoded-doc)))
decoded-doc)
#:exprs ((title "My first expression!"))
(require scribble/core
scribble/base)
(define number-of-parts #f)
(provide number-of-parts)
(section "part 1")
"hello world"
(section "part 2")
"this is another document")
(require 'example)
number-of-parts
documentation
}|
}
@section{@racketmodname[scribble/doclang]}
@defmodulelang[scribble/doclang]{The @racketmodname[scribble/doclang] language
provides the same functionality as @racketmodname[scribble/doclang2], where the
configuration options are positional and mandatory. The first three elements
in the @racket[#%module-begin]'s body must be the @racket[id],
@racket[post-process], and @racket[exprs] arguments.
Example:
@codeblock|{
#lang racket
(module* example scribble/doclang
doc
values
()
(require scribble/base)
(provide (all-defined-out))
(define foo (para "hello again"))
"hello world, this is an example document"
(para "note the " (bold "structure")))
(module+ main
(require (submod ".." example))
(printf "I see doc is: ~s\n\n" doc)
(printf "I see foo is: ~s" foo))
}|
}

10
scribble-doc/scribblings/scribble/docreader.scrbl
View File

@ -1,10 +0,0 @@
#lang scribble/doc
@(require scribble/manual scribble/bnf "utils.rkt")
@title[#:tag "docreader"]{Document Reader}
@defmodulelang[scribble/doc]{The @racketmodname[scribble/doc] language is
the same as @racketmodname[scribble/doclang], except that
@racket[read-syntax-inside] is used to read the body of the module. In
other words, the module body starts in Scribble ``text'' mode instead
of S-expression mode.}

180
scribble-doc/scribblings/scribble/eval.scrbl
View File

@ -1,180 +0,0 @@
#lang scribble/doc
@(require scribble/manual
"utils.rkt"
(for-label scribble/eval
racket/sandbox
racket/pretty
file/convertible
racket/serialize))
@(define-syntax-rule (define-new-examples new-examples)
(begin
(require (for-label scribble/example))
(define new-examples @racket[examples])))
@(define-new-examples new-examples)
@title[#:tag "old-eval"]{Legacy Evaluation}
@defmodule[scribble/eval]{The @racketmodname[scribble/eval] library provides
an older interface to the functionality of @racketmodname[scribble/example].
The @racketmodname[scribble/example] library should be used, instead.}
In addition to the forms listed below, @racket[scribble/eval]
re-exports several functions from @racket[scribble/example]:
@racket[make-base-eval] @racket[make-base-eval-factory],
@racket[make-eval-factory], @racket[make-log-based-eval],
@racket[close-eval], and @racket[scribble-eval-handler].
@defform/subs[(interaction maybe-options datum ...)
([maybe-options maybe-eval maybe-escape maybe-no-errors]
[maybe-eval code:blank
(code:line #:eval eval-expr)]
[maybe-escape code:blank
(code:line #:escape escape-id)]
[maybe-no-errors code:blank
(code:line #:no-errors? no-errors?-expr)])]{
Like @|new-examples| from @racketmodname[scribble/example], except that
@itemlist[
@item{the ``Examples:'' label is always supressed,}
@item{exceptions raised during the evaluation of a @racket[datum] are
always rendered as errors, unless @racket[#:no-errors?] is
specified with a true value; and}
@item{the @racket[#:once] option is never implicitly used.}
]
@history[#:changed "1.14" @elem{Added @racket[#:no-errors?],
@racket[eval:no-prompt], and
@racket[eval:error], and changed
@racket[code:line] to support multiple
@racket[_datum]s.}]}
@defform[(interaction0 maybe-options datum ...)]{
Like @racket[interaction], but without insetting the code via
@racket[nested].
Use @|new-examples| with @racket[#:no-indent], instead.}
@defform[(interaction/no-prompt maybe-eval maybe-escape datum)]{
Like @racket[interaction], but does not render each @racket[datum] with a prompt.
Use @|new-examples| with @racket[#:no-prompt], instead.}
@defform[(interaction-eval maybe-eval datum)]{
Like @racket[interaction], evaluates the @racket[quote]d form of
@racket[datum], but returns the empty string and does not catch
exceptions (so @racket[eval:error] has no effect).
Use @|new-examples| with @racket[#:hidden], instead.}
@defform[(interaction-eval-show maybe-eval datum)]{
Like @racket[interaction-eval], but produces an element representing
the printed form of the evaluation result.
Use @|new-examples| with @racket[#:result-only], instead.}
@defform[(racketblock+eval maybe-eval maybe-escape datum ...)]{
Combines @racket[racketblock] and @racket[interaction-eval].
Use @|new-examples| with @racket[#:no-result], instead.}
@defform[(racketblock0+eval maybe-eval maybe-escape datum ...)]{
Combines @racket[racketblock0] and @racket[interaction-eval].
Use @|new-examples| with @racket[#:no-result] and
@racket[#:no-indent], instead.}
@defform[(racketmod+eval maybe-eval maybe-escape name datum ...)]{
Combines @racket[racketmod] and @racket[interaction-eval].
Use @|new-examples| with @racket[#:lang], instead.}
@defform[(def+int maybe-options defn-datum expr-datum ...)]{
Like @racket[interaction], except the @racket[defn-datum] is
typeset as for @racket[racketblock] (i.e., no prompt) and a line of
space is inserted before the @racket[expr-datum]s.}
@defform[(defs+int maybe-options (defn-datum ...) expr-datum ...)]{
Like @racket[def+int], but for multiple leading definitions.
Use @|new-examples| with @racket[eval:no-prompt] wrappers on
definitions, instead.}
@defform[(examples maybe-options datum ...)]{
Like @racket[interaction], but with an ``Examples:'' label prefixed.
Use @|new-examples| from @racketmodname[scribble/example], instead.}
@defform[(examples* label-expr maybe-options datum ...)]{
Like @racket[examples], but using the result of @racket[label-expr] in
place of the default ``Examples:'' label.
Use @|new-examples| from @racketmodname[scribble/example] with the
@racket[#:label] option, instead.}
@defform[(defexamples maybe-options datum ...)]{
Like @racket[examples], but each definition using @racket[define] or
@racket[define-struct] among the @racket[datum]s is typeset without a
prompt, and with line of space after it.
Use @|new-examples| with @racket[eval:no-prompt] wrappers on
definitions, instead.}
@defform[(defexamples* label-expr maybe-options datum ...)]{
Like @racket[defexamples], but using the result of @racket[label-expr] in
place of the default ``Examples:'' label.
Use @|new-examples| with the @racket[#:label] option and
@racket[eval:no-prompt] wrappers on definitions, instead.}
@defproc*[([(as-examples [b block?]) block?]
[(as-examples [label (or/c block? content?)]
[b block?])
block?])]{
Adds an ``examples'' label to @racket[b], using either a default label
or the given @racket[label].}
@defform[(with-eval-preserve-source-locations expr ...)]{
By default, the evaluation forms provided by this module, such as
@racket[interaction] and @racket[examples], discard the source
locations from the expressions they evaluate. Within a
@racket[with-eval-preserve-source-locations] form, the source
locations are preserved. This can be useful for documenting forms that
depend on source locations, such as Redex's typesetting macros.
Use @|new-examples| with the @racket[#:preserve-source-locations]
option, instead.}

304
scribble-doc/scribblings/scribble/examples.scrbl
View File

@ -1,304 +0,0 @@
#lang scribble/doc
@(require scribble/manual
"utils.rkt"
(for-label scribble/example
racket/sandbox
racket/pretty
file/convertible
racket/serialize))
@title[#:tag "eval"]{Evaluation and Examples}
@defmodule[scribble/example #:use-sources (scribble/eval scribble/example)]{The
@racket[scribble/example] library provides
utilities for evaluating code at document-build time and incorporating
the results in the document, especially to show example uses of
defined procedures and syntax.}
@history[#:added "1.16"]
@defform/subs[(examples option ... datum ...)
([option (code:line #:eval eval-expr)
#:once
(code:line #:escape escape-id)
(code:line #:label label-expr)
#:hidden
#:result-only
#:no-inset
#:no-prompt
#:preserve-source-locations
#:no-result
(code:line #:lang language-name)])]{
Similar to @racket[racketinput], except that the result for each input
@racket[datum] is shown on the next line. The result is determined by
evaluating the @racket[quote]d form of the @racket[datum] using the
evaluator produced by @racket[eval-expr].
Each keyword option can be provided at most once:
@itemlist[
@item{@racket[#:eval eval-expr] --- Specifies an evaluator, where
@racket[eval-expr] must produce either @racket[#f] or a sandbox
evaluator via @racket[make-evaluator] or
@racket[make-module-evaluator] with the @racket[sandbox-output]
and @racket[sandbox-error-output] parameters set to
@racket['string]. If @racket[eval-expr] is not provided or is
@racket[#f], an evaluator is created using
@racket[make-base-eval]. See also @racket[make-eval-factory].}
@item{@racket[#:once] --- Specifies that the evaluator should be
closed with @racket[close-eval] after the all @racket[datum]s
are evaluated. The @racket[#:once] option is assumed if
@racket[#:eval] is not specified.}
@item{@racket[@#,racket[#:escape] escape-id] --- Specifies an escape
identifier, as in @racket[racketblock].}
@item{@racket[#:label label-expr] --- Specifies a label for the
examples, which defaults to ``Example:'' or ``Examples:''
(depending on the number of @racket[datum]s). A @racket[#f]
value for @racket[label-expr] suppresses the label.}
@item{@racket[#:hidden] --- Specifies that the @racket[datum]s and
results should not be typeset, but instead evaluated for a
side-effect, and disables @racket[eval:error]. Typically, this
option is combined with @racket[#:eval] to configure an
evaluator.}
@item{@racket[#:result-only] --- Specifies that the @racket[datum]
results should be typeset, but not the @racket[datum]s
themselves, and implies @racket[#:label #f].}
@item{@racket[#:no-result] --- Implies @racket[#:no-prompt] and
@racket[#:label #f], specifies that no results should be
typeset, and disables @racket[eval:error].}
@item{@racket[#:no-inset] --- Specifies that the examples should be
typeset without indentation, i.e., like @racket[racketinput0]
instead of @racket[racketinput].}
@item{@racket[#:no-prompt] --- Specifies that each examples should
be typeset without a leading prompt, i.e., like
@racket[racketblock] instead of @racket[racketinput]. A prompt
can be omitted from a specific @racket[_datum] by wrapping it
with @racket[eval:no-prompt].}
@item{@racket[#:preserve-source-locations] --- Specifies that the
original source locations for each @racket[datum] should be
preserved for evaluation. Preserving source locations can be
useful for documenting forms that depend on source locations,
such as Redex's typesetting macros.}
@item{@racket[#:lang] --- Implies @racket[#:no-result] prefixes the
typeset @racket[datum] sequence with a @hash-lang[] line using
@racket[language-name] as the module's language.}
]
Certain patterns in @racket[datum] are treated specially:
@itemlist[
@item{A @racket[datum] of the form
@racket[(@#,indexed-racket[code:line] _code-datum (@#,racketidfont{code:comment} _comment-datum ...))]
is treated as @racket[_code-datum] for evaluation.}
@item{A @racket[datum] of the form
@racket[(@#,indexed-racket[code:line] _code-datum ...)]
evaluates each @racket[_code-datum], but only the last result is used.}
@item{Other uses of @racketidfont{code:comment}, @racketidfont{code:contract}, and
@racketidfont{code:blank} are stripped from each @racket[datum]
before evaluation.}
@item{A @racket[datum] of the form
@racket[(@#,indexed-racket[eval:error] #,(svar eval-datum))] is
treated like @racket[_eval-datum], but @racket[_eval-datum] is
expected to raise an exception, and an error is shown as the
evaluation's result.}
@item{A @racket[datum] of the form
@racket[(@#,indexed-racket[eval:alts] #,(svar show-datum) #,(svar eval-datum))]
is treated as @svar[show-datum] for typesetting and @svar[eval-datum] for evaluation.}
@item{A @racket[datum] of the form
@racket[(@#,indexed-racket[eval:check] #,(svar eval-datum) #,(svar expect-datum))]
is treated like @racket[_eval-datum], but @svar[check-datum] is also
evaluated, and an error is raised if they are not @racket[equal?].}
@item{A @racket[datum] of the form
@racket[(@#,indexed-racket[eval:result] _content-expr _out-expr _err-expr)]
involves no sandboxed evaluation; instead, the @tech{content} result of @racket[_content-expr] is used as the
typeset form of the result, @racket[_out-expr] is treated as output printed
by the expression, and @racket[_err-expr] is error output printed by the
expression. The @racket[_out-expr] and/or @racket[_err-expr] can be omitted,
in which case they default to empty strings.
Normally, @racketidfont{eval:result}
is used in the second part of an @racketidfont{eval:alts} combination. Otherwise,
@racket[_content-expr] is typeset as the input form (which rarely makes sense for
a reader of the example).}
@item{A @racket[datum] of the form
@racket[(@#,indexed-racket[eval:results] _content-list-expr _out-expr _err-expr)]
is treated like an @racketidfont{eval:result} form, except that @racket[_content-list-expr]
should produce a list of @tech{content} for multiple results of evaluation. As
with @racketidfont{eval:result}, @racket[_out-expr] and @racket[_err-expr] are optional.}
@item{A @racket[datum] of the form
@racket[(@#,indexed-racket[eval:no-prompt] _eval-datum ...)]
is treated like @racket[(@#,racket[code:line] _eval-datum ...)], but no prompt is shown before
the group, and a blank line is added before and after
@(svar eval-datum) and its result.}
]
A @racket[datum] cannot be a keyword. To specify a @racket[datum] that
is a keyword, wrap it with @racket[code:line].
When evaluating a @racket[datum] produces an error (and @racket[datum]
does not have an @racket[eval:error] wrapper), an exception is raised
by @racket[examples].
If the value of @racket[current-print] in the sandbox is changed from
its default value, or if @racket[print-as-expression] in the sandbox
is set to @racket[#f], then each evaluation result is formatted to a
port by applying @racket[(current-print)] to the value; the output
port is set to a pipe that supports specials in the sense of
@racket[write-special], and non-character values written to the port
are used as @tech{content}. Otherwise, when the default
@racket[current-print] is in place, result values are typeset using
@racket[to-element/no-color].
As an example,
@codeblock|{
#lang scribble/manual
@(require racket/sandbox
scribble/eval)
@(define my-evaluator
(parameterize ([sandbox-output 'string]
[sandbox-error-output 'string])
(make-evaluator 'typed/racket/base)))
@examples[#:eval my-evaluator
(: my-sqr (Real -> Real))
(define (my-sqr x)
(* x x))
(my-sqr 42)]
}|
uses an evaluator whose language is @racketmodname[typed/racket/base].}
@defproc[(make-base-eval [#:pretty-print? pretty-print? any/c #t]
[#:lang lang
(or/c module-path?
(list/c 'special symbol?)
(cons/c 'begin list?))
'(begin)]
[input-program any/c] ...)
(any/c . -> . any)]{
Creates an evaluator using @racket[(make-evaluator 'racket/base #:lang lang input-program ...)],
setting sandbox parameters to disable limits, setting the outputs to
@racket['string], and not adding extra security guards.
If @racket[pretty-print?] is true, the sandbox's printer is set to
@racket[pretty-print-handler]. In that case, values that are convertible
in the sense of @racket[convertible?] are printed using @racket[write-special],
except that values that are serializable in the sense of @racket[serializable?]
are serialized for tranfers from inside the sandbox to outside (which can avoid
pulling code and support from the sandboxed environment into the document-rendering
environment).
@history[#:changed "1.6" @elem{Changed treatment of convertible values that are
serializable.}]}
@defproc[(make-base-eval-factory [mod-paths (listof module-path?)]
[#:pretty-print? pretty-print? any/c #t]
[#:lang lang
(or/c module-path?
(list/c 'special symbol?)
(cons/c 'begin list?))
'(begin)])
(-> (any/c . -> . any))]{
Produces a function that is like @racket[make-base-eval], except that
each module in @racket[mod-paths] is attached to the evaluator's
namespace. The modules are loaded and instantiated once (when the
returned @racket[make-base-eval]-like function is called the first
time) and then attached to each evaluator that is created.}
@defproc[(make-eval-factory [mod-paths (listof module-path?)]
[#:pretty-print? pretty-print? any/c #t]
[#:lang lang
(or/c module-path?
(list/c 'special symbol?)
(cons/c 'begin list?))
'(begin)])
(-> (any/c . -> . any))]{
Like @racket[make-base-eval-factory], but each module in @racket[mod-paths] is
also required into the top-level environment for each generated evaluator.}
@defproc[(make-log-based-eval [log-file path-string?]
[mode (or/c 'record 'replay)])
(-> any/c any)]{
Creates an evaluator (like @racket[make-base-eval]) that uses a log
file to either record or replay evaluations.
If @racket[mode] is @racket['record], the evaluator records every
interaction to @racket[log-file], replacing @racket[log-file] if it
already exists. The result of each interaction must be
@seclink["serialization" #:doc '(lib
"scribblings/reference/reference.scrbl")]{serializable}.
If @racket[mode] is @racket['replay], the evaluator uses the contents
of @racket[log-file] instead of actually performing evaluatings. For
each interaction, it compares the term to evaluate against the next
interaction recorded in @racket[log-file]. If the term matches, the
stored result is returned; if not, the evaluator raises an error
indicating that it is out of sync with @racket[log-file].
Use @racket[make-log-based-eval] to document libraries when the
embedded examples rely on external features that may not be present or
appropriately configured on all machines.
@history[#:added "1.12"]}
@defproc[(close-eval [eval (any/c . -> . any)]) (one-of/c "")]{
Shuts down an evaluator produced by @racket[make-base-eval]. Use
@racket[close-eval] when garbage collection cannot otherwise reclaim
an evaluator (e.g., because it is defined in a module body).}
@defparam[scribble-eval-handler handler
((any/c . -> . any) any/c boolean? . -> . any)]{
A parameter that serves as a hook for evaluation. The evaluator to use
is supplied as the first argument to the parameter's value, and the
second argument is the form to evaluate. The last argument is
@racket[#t] if exceptions are being captured (to display exception
results), @racket[#f] otherwise.}
@defparam[scribble-exn->string handler (-> (or/c exn? any/c) string?)]{
A parameter that controls how exceptions are rendered by
@racket[interaction]. Defaults to
@racketblock[(λ (e)
(if (exn? e)
(exn-message e)
(format "uncaught exception: ~s" e)))]
}
@; ------------------------------------------------------------
@include-section["eval.scrbl"]

14
scribble-doc/scribblings/scribble/generic.scrbl
View File

@ -1,14 +0,0 @@
#lang scribble/manual
@(require "utils.rkt")
@title[#:tag "generic-prose" #:style 'toc]{High-Level Scribble API}
@local-table-of-contents[]
@include-section["base.scrbl"]
@include-section["manual-stub.scrbl"]
@include-section["book.scrbl"]
@include-section["report.scrbl"]
@include-section["sigplan.scrbl"]
@include-section["jfp.scrbl"]
@include-section["lncs.scrbl"]

10
scribble-doc/scribblings/scribble/getting-started.scrbl
View File

@ -1,10 +0,0 @@
#lang scribble/manual
@title[#:tag "getting-started" #:style 'toc]{Getting Started}
@local-table-of-contents[]
@include-section["how-to-paper.scrbl"]
@include-section["how-to.scrbl"]

682
scribble-doc/scribblings/scribble/how-to-paper.scrbl
View File

@ -1,682 +0,0 @@
#lang scribble/doc
@(require scribble/manual scribble/bnf "utils.rkt"
pict
(for-label scriblib/figure scribble/base scribble/sigplan
(except-in pict table)))
@(define-syntax-rule (samplemod . text) (codeblock . text))
@(define-syntax-rule (sample a . text)
(codeblock #:context #'a #:keep-lang-line? #f
"#lang scribble/base" "\n" a . text))
@(define (result . text) (apply nested #:style 'inset text))
@(define sep @hspace[1])
@(define sub*section subsection)
@title[#:tag "getting-started"]{Getting Started}
No matter what you want to do with Scribble, it's best to start by
generating a few simple HTML and/or PDF documents. This chapter steps
you through the basics, and it ends in @secref["roadmap"] with
goal-specific advice on how to continue.
@section[#:tag "first-example"]{A First Example}
Create a file @filepath{mouse.scrbl} with this content:
@samplemod|{
#lang scribble/base
@title{On the Cookie-Eating Habits of Mice}
If you give a mouse a cookie, he's going to ask for a
glass of milk.
}|
The first line's @racket[#, @hash-lang[] #,
@racketmodname[scribble/base]] indicates that the file implements a
Scribble document. The document starts in ``text mode,'' and the
@litchar["@"] character escapes to operators like @racket[title],
where the curly braces return to text mode for the arguments to the
operator. The rest is document content.
Now run the @exec{scribble} command-line program, specifying a mode
for the kind of document that you want as output:
@itemize[
@item{Run
@commandline{scribble mouse.scrbl}
to generate HTML as @filepath{mouse.html}. You may
notice that the apostrophe in ``he's'' turned into a
curly apostrophe.}
@item{Run
@commandline{scribble --htmls mouse.scrbl}
to generate HTML as @filepath{mouse/index.html}.
Sub-sections (which we add next) will appear as separate
HTML files in the @filepath{mouse} directory.}
@item{Run
@commandline{scribble --pdf mouse.scrbl}
to generate PDF as @filepath{mouse.pdf}. This will
work only if you have @exec{pdflatex} installed.
If you'd like to see the intermediate Latex, try
@commandline{scribble --latex mouse.scrbl}
to generate @filepath{mouse.tex}.}
]
See @secref["running"] for more information on the @exec{scribble}
command-line tool.
@section{Multiple Sections}
Add more text to @filepath{mouse.scrbl} so that it looks like this:
@samplemod|{
#lang scribble/base
@title{On the Cookie-Eating Habits of Mice}
If you give a mouse a cookie, he's going to ask for a
glass of milk.
@section{The Consequences of Milk}
That ``squeak'' was the mouse asking for milk. Let's
suppose that you give him some in a big glass.
He's a small mouse. The glass is too big---way too
big. So, he'll probably ask you for a straw. You might as
well give it to him.
@section{Not the Last Straw}
For now, to handle the milk moustache, it's enough to give
him a napkin. But it doesn't end there... oh, no.
}|
Now, after the first paragraph of the paper, we have two
sub-sections, each created by calling @racket[section] to
generate a sub-section declaration. The first sub-section has
two paragraphs. The second section, as initiated by the result
of the second @racket[section] call, has a single paragraph.
Run the @exec{scribble} command(s) from @secref["first-example"]
again. You may notice the curly double-quotes in the output, and
the @litchar{---} turned into an em dash.
@;----------------------------------------
@section{Splitting the Document Source}
As a document grows larger, it's better to split sections into
separate source files. The @racket[include-section] operation
incorporates a document defined by a @filepath{.scrbl} file into a
larger document.
To split the example document into multiple files, change
@filepath{mouse.scrbl} to just
@samplemod|{
#lang scribble/base
@title{On the Cookie-Eating Habits of Mice}
If you give a mouse a cookie, he's going to ask for a
glass of milk.
@include-section["milk.scrbl"]
@include-section["straw.scrbl"]
}|
Create @filepath{milk.scrbl} and @filepath{straw.scrbl} in the same
directory as @filepath{mouse.scrbl}. In @filepath{milk.scrbl}, put
@samplemod|{
#lang scribble/base
@title{The Consequences of Milk}
That ``squeak'' was the mouse asking for milk...
}|
and in @filepath{straw.scrbl}, put
@samplemod|{
#lang scribble/base
@title{Not the Last Straw}
For now, to handle the milk moustache, ...
}|
Notice that the new files both start with @hash-lang[], like the
original document, and the @racket[section]s from the original
document become @racket[title]s in the new documents. Both
@filepath{milk.scrbl} and @filepath{straw.scrbl} are documents in
their own right with their own titles, and they can be individually
rendered using @exec{scribble}. Running @exec{scribble} on
@filepath{mouse.scrbl}, meanwhile, incorporates the smaller documents
into one document that is the same as before.
@; ----------------------------------------
@section{Document Styles}
Scribble currently supports only one form of HTML output. You can
replace the @filepath{scribble.css} file for the generated pages, and
that's about it. (We expect to add more styles in the future.)
For Latex-based PDF output, Scribble includes support for
multiple page-layout configurations. The @filepath{mouse.scrbl}
example so far uses the default Latex style. If you plan on submitting
the paper to a workshop on programming languages, then---well, you
probably need a different topic. But you can start making the current
content look right by changing the first line to
@samplemod|{
#lang scribble/sigplan
}|
If you're instead working toward Racket library documentation,
try changing the first line to
@samplemod|{
#lang scribble/manual
}|
which produces output with a separate title page, initial content on
that page (intended as a brief orientation to the document), and
top-level sections turned into chapters that each start on a new page.
If you have split the document into multiple files, the first line of
the main document file determines the output format.
Using @racketmodname[scribble/sigplan] or
@racketmodname[scribble/manual] does not change the rendered HTML for
a document---aside from @racketmodname[scribble/manual] adding a
version number---but it changes the set of bindings available in the
document body. For example, with @racketmodname[scribble/sigplan], the
introductory text can be marked as an abstract:
@samplemod|{
#lang scribble/sigplan
@title{On the Cookie-Eating Habits of Mice}
@abstract{If you give a mouse a cookie, he's going to
ask for a glass of milk.}
@section{The Consequences of Milk}
....}|
When rendered as HTML, the abstract shows up as an inset paragraph. If
you try to use @racket[abstract] with the
@racketmodname[scribble/base] or @racketmodname[scribble/manual]
language, then you get an error, because @racket[abstract] is not
defined.
When a document is implemented across multiple files, changing the
language of the main document can set the style for all of the parts,
but it does not introduce bindings into the other part files. For
example, if you change the language of @filepath{mouse.scrbl} to
@racketmodname[scribble/sigplan], then @racket[abstract] becomes
available in @filepath{mouse.scrbl} but not in @filepath{milk.scrbl}
or @filepath{straw.scrbl}. In other words, operator names are
lexically scoped.
@; ----------------------------------------
@section{More Functions}
The @racketmodname[scribble/base] language provides a collection of
basic operations (and The @racketmodname[scribble/sigplan] and
@racketmodname[scribble/manual] are supersets of
@racketmodname[scribble/base]). Many of the operations are style
variations that you can apply to text:
@sample|{
He's a @smaller{small mouse}. The glass is too
@larger{big}---@bold{way @larger{too @larger{big}}}. So, he'll
@italic{probably} ask you for a straw.
}|
which renders as
@result{
He's a @smaller{small mouse}. The glass is too
@larger{big}---@bold{way @larger{too @larger{big}}}. So, he'll
@italic{probably} ask you for a straw.
}
As you would expect, calls to functions like @racket[smaller],
@racket[larger], and @racket[bold] can be nested in other calls. They
can also be nested within calls to @racket[title] or @racket[section]:
@sample|{
@section{@italic{Not} the Last Straw}
}|
@sub*section{Centering}
The @racket[centered] operation centers a flow of text:
@sample|{
If a mouse eats all your cookies, put up a sign that says
@centered{
@bold{Cookies Wanted}
@italic{Chocolate chip preferred!}
}
and see if anyone brings you more.
}|
which renders as
@result{
If a mouse eats all your cookies, put up a sign that says
@centered{
@bold{Cookies Wanted}
@italic{Chocolate chip preferred!}
}
and see if anyone brings you more.
}
@sub*section{Margin Notes}
The @racket[margin-note] operation is used in a similar way, but the
rendered text is moved to the margins.
@margin-note*{If you use @racket[margin-note], then the content shows
up over here.}
@sub*section{Itemizations}
The @racket[itemlist] operation creates a sequence of bulleted text,
where the @racket[item] operation groups text to appear in a single
bullet. The @racket[itemlist] operation is different from the others
that we have seen before, because it only accepts values produced by
@racket[item] instead of arbitrary text. This difference is reflected
in the use of @litchar{[}...@litchar{]} for the arguments to
@racket[itemlist] instead of @litchar["{"]...@litchar["}"]:
@sample|{
@centered{@bold{Notice to Mice}}
@itemlist[@item{We have cookies for you.}
@item{If you want to eat a cookie,
you must bring your own straw.}]
}|
which renders as
@result{
@centered{@bold{Notice to Mice}}
@itemlist[@item{We have cookies for you.}
@item{If you want to eat a cookie,
you must bring your own straw.}]
}
@sub*section{Tables}
The @racket[tabular] function takes a list of lists to organize into a
two-dimensional table. By default, no spacing is added between columns,
so supply a @racket[#:sep] argument to acts as a column separator.
For example,
@sample|{
@tabular[#:sep @hspace[1]
(list (list @bold{Animal} @bold{Food})
(list "mouse" "cookie")
(list "moose" "muffin"))]
}|
renders as
@result{
@tabular[#:sep @hspace[1]
(list (list @bold{Animal} @bold{Food})
(list "mouse" "cookie")
(list "moose" "muffin"))]
}
@; ----------------------------------------
@section{Text Mode vs. Racket Mode for Arguments}
When @litchar{[}...@litchar{]} surrounds the arguments of an
operation, the argument expressions are in Racket mode rather than
text mode. Even in Racket mode, @litchar["@"] can be used to apply
operations; once the @"@" syntax is enabled through a
language like @racketmodname[scribble/base] (as opposed to
@racketmodname[racket]), it behaves the same in both Racket mode and
text mode.
One advantage of using Racket mode for the arguments to
@racket[itemlist] is that we can pass a keyword-tagged optional
argument to @racket[itemlist]. In particular, if you want a list with
numbers instead of bullets, supply the @racket['ordered] style to
@racket[itemlist] using the @racket[#:style] keyword:
@sample|{
@itemlist[#:style 'ordered
@item{Eat cookie.}
@item{Drink milk.}
@item{Wipe mouth.}
@item{...}]
}|
An operation doesn't care whether it's used with
@litchar{[}...@litchar{]} or @litchar["{"]...@litchar["}"]. Roughly,
@litchar["{"]...@litchar["}"] forms an argument that is a
string. (Only roughly, though. Newlines or uses of @litchar["@"]
within @litchar["{"]...@litchar["}"] complicate the picture, and we'll
get back to that soon.) So,
@sample|{
@italic{Yummy!}
}|
is equivalent to
@sample|{
@italic["Yummy!"]
}|
which is equivalent to the Racket expression
@racketblock[
(italic "Yummy!")
]
These equivalences explain why Scribble functions are documented in
Racket notation. If you're reading this in HTML format, you can click
@racket[italic] above to access its documentation. The documentation
won't completely make sense, yet, but it will by the end of this
chapter.
What if you want to provide arguments in text mode, but you also want
to supply other optional arguments? You can use both
@litchar{[}...@litchar{]} and @litchar["{"]...@litchar["}"] for an
operation, as long as the @litchar{[}...@litchar{]} is first, and as
long as no character separate the closing @litchar{]} from the
opening @litchar["{"]. For example, calling @racket[italic] is the
same as using @racket[elem] with the @racket['italic] style:
@sample|{
@elem[#:style 'italic]{Yummy!}
}|
You can also @emph{omit} both @litchar{[}...@litchar{]} and
@litchar["{"]...@litchar["}"]. In that case, the Racket expression
after @litchar["@"] is used directly instead of applied as an
operation. For example,
@sample|{
1 plus 2 is @(number->string (+ 1 2)).
}|
renders as
@result{
1 plus 2 is @(number->string (+ 1 2)).
}
The call to @racket[number->string] is needed because a naked number
is not valid as document content.
@; ----------------------------------------
@section[#:tag "how-to:reader"]{@"@" Syntax Basics}
The @"@" notation provided by Scribble is just another way of
writing Racket expressions. Scribble documents could be constructed
using normal Racket notation, without using @"@" at all, but
that would be inconvenient for most purposes. The @"@"
notation makes dealing with textual content much easier.
Whether in text mode or Racket mode, @litchar["@"] in a document
provides an escape to Racket mode. The basic syntax of @litchar["@"] is
@racketblock[
@#,BNF-seq[@litchar["@"]
@nonterm{cmd}
@litchar{[} @kleenestar{@nonterm{datum}} @litchar{]}
@litchar["{"] @nonterm{text-body} @litchar["}"]]
]
where all three parts after @litchar["@"] are optional, but at least
one must be present. No spaces are allowed between
@itemize[
@item{@litchar["@"] and @nonterm{cmd}, @litchar{[}, or @litchar["{"]}
@item{@nonterm{cmd} and @litchar{[} or @litchar["{"]; or}
@item{@litchar{]} and @litchar["{"].}
]
A @nonterm{cmd} or @nonterm{datum} is normal Racket notation, while a
@nonterm{text-body} is itself in text mode. A @nonterm{cmd} obviously
must not start with @litchar{[} or @litchar["{"], even though Racket
forms could otherwise start with those characters.
The expansion of just @litchar["@"]@nonterm{cmd} into Racket code is
@racketblock[
@#,nonterm{cmd}
]
When either @litchar{[} @litchar{]} or @litchar["{"] @litchar["}"]
are used, the expansion is
@racketblock[
(@#,nonterm{cmd} @#,kleenestar{@nonterm{datum}} @#,kleenestar{@nonterm{parsed-body}})
]
where @kleenestar{@nonterm{parsed-body}} is the parse result of the
@nonterm{text-body}. The @kleenestar{@nonterm{parsed-body}} part often
turns out to be a sequence of Racket strings.
In practice, the @nonterm{cmd} is normally a Racket identifier that is
bound to a procedure or syntactic form. If the procedure or form
expects further text to typeset, then @litchar["{"]...@litchar["}"]
supplies the text. If the form expects other data, typically
@litchar{[}...@litchar{]} is used to surround Racket arguments,
instead. Even if an operation's argument is a string, if the string is
not used as content text (but instead used as, say, a hyperlink
label), then the string is typically provided through
@litchar{[}...@litchar{]} instead of @litchar["{"]...@litchar["}"].
Sometimes, both @litchar{[}...@litchar{]} and
@litchar["{"]...@litchar["}"] are used, where the former surround
Racket arguments that precede text to typeset. Finally, if a form is a
purely Racket-level form with not typeset result, such as a
@racket[require] to import more operations, then typically just
@litchar["@"] is used.
For example the text-mode stream
@sample|{
@(require scriblib/figure)
@section[#:tag "poetry"]{Of Mice and Cookies}
See @secref["milk"].
@section[#:tag "milk"]{@italic{Important} Milk Supplies}
@figure["straw" @elem{A straw}]{@image["straw.png"]}
}|
is equivalent to the Racket-mode sequence
@racketblock[
(require scriblib/figure) "\n"
"\n"
(section #:tag "poetry" "Of Mice and Cookies") "\n"
"See " (secref "milk") "." "\n"
"\n"
(section #:tag "milk" (italic "Important") " Milk Supplies") "\n"
(figure "straw" (elem "A straw") (image "straw.png")) "\n"
]
Besides showing how different argument conventions are used for
different operations, the above example illustrates how whitespace is
preserved in the Racket form of a text-mode stream---including
newlines preserved as their own strings. Notice how the second
@racket[section] gets two arguments for its content, since the
argument content for @racket[section] in the source stream includes
both the use of an operator and additional text. When an operation
like @racket[section] or @racket[italic] accepts content to typeset,
it normally accepts an arbitrary number of arguments that together
form the content.
In addition to its role for command, a @litchar["@"] can be followed
by @litchar{;} to start a @index['("Scribble"
"comments")]{comment}. If the character after @litchar{;} is
@litchar["{"], then the comment runs until a matching @litchar["}"],
otherwise the comment runs until the end-of-line:
@racketblock[
@#,BNF-seq[@litchar["@;{"] @nonterm{comment} @litchar["}"]]
@#,BNF-seq[@litchar["@;"] @nonterm{line-comment}]
]
For more information on the syntax of @litchar["@"], see
@secref["reader"]. The full syntax includes a few more details, such
as brackets like @litchar["|{"]...@litchar["}|"] for text-mode
arguments while disabling @litchar["@"] between the brackets.
@; ----------------------------------------
@section{Decoding Sequences}
In a document that starts @racket[#, @hash-lang[] #,
@racketmodname[scribble/base]], the top level is a text-mode stream,
just like the @nonterm{text-body} in a @litchar["@"] form. As
illustrated in the previous section, such a top-level sequence
corresponds to a mixture of Racket-mode strings and operation
applications. There's an implicit operation, @racket[decode], that
wraps the whole document to consume this mixture of strings and other
values and turn them into a document description.
The @racket[decode] operation implements @defterm{flow decoding},
which takes a document stream and breaks it up into sections and
paragraphs. Blank lines delimit paragraphs, and the results of
operations like @racket[title] and @racket[section] generate ``here's
the title'' or ``a new section starts here'' declarations that are
recognized by @racket[decode].
A different but related @defterm{content decoding} takes place within
a paragraph or section title. Content decoding is responsible for
converting @litchar{---} to an em dash or for converting @litchar{"}
and @litchar{'} to suitable curly quotes.
The decoding process for document's stream is ultimately determined by
the @hash-lang[] line that starts the document. The
@racketmodname[scribble/base], @racketmodname[scribble/manual], and
@racketmodname[scribble/sigplan] languages all use the same
@racket[decode] operation. The @racketmodname[scribble/text] language,
however, acts more like a plain-text generator and preprocessor, and it
does not perform any such decoding rules. (For more on
@racketmodname[scribble/text], see @other-doc['(lib
"scribblings/scribble/scribble-pp.scrbl")].)
@margin-note{More precisely, languages like
@racketmodname[scribble/base] apply @racket[decode] only after
lifting out all definitions and imports from the document
stream.}
When the flow decoder is used, after it breaks the input stream into
paragraphs, it applies content decoding to strings within the
paragraph. When content is wrapped with an operation, however, content
decoding does not apply automatically. An operation is responsible for
calling a content or flow decoder as it sees fit. Most operations call
the decoder; for example, @racket[italic], @racket[bold],
@racket[smaller], etc., all decode their arguments. Similarly,
@racket[title] and @racket[section] decode the given content for the
title or section name. The @racket[literal] and @racket[verbatim]
operators, however, do not decode the given strings. For example,
@sample|{
@verbatim{---}
}|
renders as
@result{
@verbatim{---}
}
Don't confuse decoding with the expansion of @"@"
notation. The source form
@sample|{
@verbatim{@(number->string (+ 1 2))}
}|
renders as
@result{
@verbatim{@(number->string (+ 1 2))}
}
because the source is equivalent to
@racketblock[
(verbatim (number->string (+ 1 2)))
]
where @racket[(number->string (+ 1 2))] is evaluated to produce the
argument to @racket[verbatim]. The @litchar["|{"]...@litchar["}|"]
style of brackets is often used with @racket[verbatim], because
@litchar["|{"]...@litchar["}|"] disables @"@" notation for
arguments. For example,
@sample|{
@verbatim|{@(number->string (+ 1 2))}|
}|
renders as
@result{
@verbatim|{@(number->string (+ 1 2))}|
}
@; ----------------------------------------
@section[#:tag "pictures"]{Pictures}
Any value that is convertable to an image can be used directly within
a Scribble document. Functions from the @racketmodname[pict]
and @racketmodname[2htdp/image #:indirect] libraries, for example, generate
images. For example,
@sample|{
@(require pict)
This cookie has lost its chocolate chips:
@(colorize (filled-ellipse 40 40) "beige").
}|
renders as
@result{
This cookie has lost its chocolate chips:
@(colorize (filled-ellipse 40 40) "beige").
}
@; ----------------------------------------
@section[#:tag "roadmap"]{Next Steps}
If your immediate goal is to document a Racket library or write
literate programs, skip to @secref["how-to-doc"], and then go back to
@secref["reader"] and other chapters.
If you are more interested in producing documents unrelated to
Racket, continue with @secref["reader"] and then
@secref["generic-prose"]. Move on to @secref["internals"] when you
need more power.
If you are interested in text generation and preprocessing, continue
with @secref["reader"], but then switch to
@other-doc['(lib "scribblings/scribble/scribble-pp.scrbl")].

381
scribble-doc/scribblings/scribble/how-to.scrbl
View File

@ -1,381 +0,0 @@
#lang scribble/doc
@(require scribble/manual scribble/bnf "utils.rkt")
@(define pkg-doc '(lib "pkg/scribblings/pkg.scrbl"))
@title[#:tag "how-to-doc"]{Getting Started with Documentation}
Although the @exec{scribble} command-line utility generates output
from a Scribble document, documentation of Racket libraries is
normally built by @exec{raco setup}. This chapter emphasizes the
@exec{raco setup} approach, which more automatically supports links
across documents.
@margin-note{See @secref["getting-started"] for information on using the
@exec{scribble} command-line utility.}
@;----------------------------------------
@section[#:tag "setting-up"]{Setting Up Library Documentation}
To document a collection, including a collection implemented by a
@seclink["getting-started" #:doc pkg-doc]{package}:
@itemize[
@item{Create a file in your collection with the
file extension @filepath{.scrbl}. Beware that the file name
you choose will determine the output directory's name, and
the directory name must be unique across all installed documents. The
remainder of these instructions assume that the file is called
@filepath{manual.scrbl} (but pick a more specific name in practice).}
@item{Start @filepath{manual.scrbl} like this:
@codeblock|{
#lang scribble/manual
@title{My Library}
Welcome to my documentation: @racket[(list 'testing 1 2 3)].
}|
The first line starts the file in ``text'' mode and selects
the Racket manual output format.
It also introduces bindings like @racket[title] and
@racket[racket] for writing Racket documentation.}
@item{Add the following entry to your collection's
@filepath{info.rkt}:
@racketblock[
(define scribblings '(("manual.scrbl" ())))
]
The @racket[()] above is a list of options. When your document
gets large enough that you want it split into multiple pages,
add the @racket['multi-page] option (omitting the quote, since
the whole right-hand side of the definition is already
quoted).
If you do not already have an @filepath{info.rkt} module,
here's a suitable complete module:
@racketmod[
info
(define scribblings '(("manual.scrbl" ())))
]}
@item{Run @exec{raco setup} to build your documentation. For a
collection, optionally supply @Flag{l} followed by the
collection name to limit the build process to that
collection.}
@item{For a collection that is installed as user-specific
(e.g., the user @tech[#:doc pkg-doc]{package scope}), the generated
documentation is @filepath{doc/manual/index.html} within the
collection directory. If the collection is installation-wide,
however, then the documentation
is generated as @filepath{manual/index.html} in the
installation's @filepath{doc} directory.}
]
@; ----------------------------------------
@section[#:tag "racket-hyperlinks"]{Racket Typesetting and Hyperlinks}
In the document source at the start of this chapter
(@secref["setting-up"]), the Racket expression
@racket[(#,(racketidfont "list") 'testing 1 2 3)] is typeset properly,
but the @racketidfont{list} identifier is not hyperlinked to the usual
definition. To cause @racketidfont{list} to be hyperlinked, add a
@racket[require] form like this:
@codeblock[#:keep-lang-line? #f]|{
#lang scribble/base
@(require (for-label racket))
}|
This @racket[require] with @racket[for-label] declaration introduces a
document-time binding for each export of the @racketmodname[racket]
module. When the document is built, the @racket[racket] form detects
the binding for @racket[list], and so it generates a reference to the
specification of @racket[list]. The setup process detects the
reference, and it finds the matching specification in the existing
documentation, and ultimately directs the hyperlink to that
specification.
Hyperlinks based on @racket[for-label] and @racket[racket] are the
preferred mechanism for linking to information outside of a single
document. Such links require no information about where and how a
binding is documented elsewhere:
@codeblock|{
#lang scribble/manual
@(require (for-label racket))
@title{My Library}
See also @racket[list].
}|
The @racket[racket] form typesets a Racket expression for inline text,
so it ignores the source formatting of the expression. The
@racket[racketblock] form, in contrast, typesets inset Racket code,
and it preserves the expression's formatting from the document source.
@codeblock|{
#lang scribble/manual
@(require (for-label racket))
@title{My Library}
Some example Racket code:
@racketblock[
(define (nobody-understands-me what)
(list "When I think of all the"
what
"I've tried so hard to explain!"))
(nobody-understands-me "glorble snop")
]
}|
@; ----------------------------------------
@section[#:tag "section-hyperlinks"]{Section Hyperlinks}
A @racket[section] declaration in a document can include a
@racket[#:tag] argument that declares a hyperlink-target tag. The
@racket[secref] function generates a hyperlink, using the section name
as the text of the hyperlink. Use @racket[seclink] to create a
hyperlink with text other than the section title.
The following example illustrates section hyperlinks:
@codeblock|{
#lang scribble/manual
@(require (for-label racket))
@title{My Library}
Welcome to my documentation: @racket[(list 'testing 1 2 3)].
@table-of-contents[]
@section[#:tag "chickens"]{Philadelphia Chickens}
Dancing tonight!
@section{Reprise}
See @secref{chickens}.
}|
Since the page is so short, the hyperlinks in the above example are
more effective if you change the @filepath{info.rkt} file to add the
@racket['multi-file] flag:
@racketblock[
(define scribblings '(("manual.scrbl" (multi-page))))
]
A section can have a @techlink{tag prefix} that applies to all tags as
seen from outside the section. Such a prefix is automatically given to
each top-level document as processed by @exec{raco setup}. Thus,
referencing a section tag in a different document requires using a
prefix, which is based on the target document's main source file. The
following example links to a section in the Racket reference
manual:
@codeblock|{
#lang scribble/manual
@(require (for-label racket))
@(define ref-src
'(lib "scribblings/reference/reference.scrbl"))
@title{My Library}
See also @italic{@secref[#:doc ref-src]{pairs}}.
}|
As mentioned in @secref{racket-hyperlinks}, however, cross-document
references based on @racket[(require (for-label ....))] and
@racket[racket] are usually better than cross-document references
using @racket[secref].
@; ----------------------------------------
@section{Defining Racket Bindings}
Use @racket[defproc] to document a procedure, @racket[defform] to
document a syntactic form, @racket[defstruct] to document a structure
type, etc. These forms provide consistent formatting of definitions,
and they declare hyperlink targets for @racket[racket]-based
hyperlinks.
To document a @racket[my-helper] procedure that is exported by
@filepath{helper.rkt} in the @filepath{my-lib} collection that contains
@filepath{manual.scrbl}:
@itemize[
@item{Use @racket[(require (for-label "helper.rkt"))] to import the
binding information about the bindings of @filepath{helper.rkt}
for use when typesetting identifiers. A relative reference
@racket["helper.rkt"] works since it is relative to the
documentation source.}
@item{Add a @tt|{@defmodule[my-lib/helper]}| declaration, which
specifies the library that is being documented within the
section. The @racket[defmodule] form needs an absolute module
name @racket[mylib/helper], instead of a relative reference
@racket["helper.rkt"], since the module path given to
@racket[defmodule] appears verbatim in the generated
documentation.}
@item{Use @racket[defproc] to document the procedure.}
]
Adding these pieces to @filepath{manual.scrbl} gives us the
following:
@codeblock|{
#lang scribble/manual
@(require (for-label racket
"helper.rkt"))
@title{My Library}
@defmodule[my-lib/helper]
@defproc[(my-helper [lst list?])
(listof
(not/c (one-of/c 'cow)))]{
Replaces each @racket['cow] in @racket[lst] with
@racket['aardvark].}
}|
In @racket[defproc], a contract is specified with each argument to the
procedure. In this example, the contract for the @racket[_lst]
argument is @racket[list?], which is the contract for a list. After
the closing parenthesis that ends the argument sequence, the contract
of the result must be given; in this case, @racket[my-helper]
guarantees a result that is a list where none of the elements are
@racket['cow].
Some things to notice in this example and the documentation that it
generates:
@itemize[
@item{The @racket[list?], @racket[listof], @|etc| elements of
contracts are hyperlinked to their documentation.}
@item{The result contract is formatted in the generated documentation
in the same way as in the source. That is, the source layout of
contracts is preserved. (In this case, putting the contract all
on one line would be better.)}
@item{In the prose that documents @racket[my-helper], @racket[_lst]
is automatically typeset in italic, matching the typesetting in
the blue box. The @racket[racket] form essentially knows that
it's used in the scope of a procedure with argument
@racket[_lst].}
@item{If you hover the mouse pointer over @racket[my-helper], a popup
reports that it is provided from @racketidfont{my-lib/helper}.}
@item{If you use @racket[my-helper] in any documentation now, as long
as that documentation source also has a @racket[(require
(for-label ....))] of @filepath{helper.rkt}, then the
reference is hyperlinked to the definition above.}
]
See @racket[defproc*], @racket[defform], @|etc| for more information
on forms to document Racket bindings.
@; ----------------------------------------
@section{Showing Racket Examples}
The @racket[examples] form from @racket[scribble/eval] helps you
generate examples in your documentation. To use @racket[examples], the
procedures to document must be suitable for use at documentation time,
but the @racket[examples] form does not use any binding introduced
into the document source by @racket[require]. Instead, create a new
evaluator with its own namespace using @racket[make-base-eval], and
use @racket[interaction-eval] to require @filepath{helper.rkt} in that
evaluator. Finally, supply the same evaluator to @racket[examples]:
@codeblock|{
#lang scribble/manual
@(require scribble/eval
(for-label racket
"helper.rkt"))
@title{My Library}
@defmodule[my-lib/helper]
@defproc[(my-helper [lst list?])
(listof
(not/c (one-of/c 'cow)))]{
Replaces each @racket['cow] in @racket[lst] with
@racket['aardvark].
@(define helper-eval (make-base-eval))
@interaction-eval[#:eval helper-eval
(require "helper.rkt")]
@examples[
#:eval helper-eval
(my-helper '())
(my-helper '(cows such remarkable cows))
]}
}|
@;----------------------------------------
@section{Multi-Page Sections}
Setting the @racket['multi-page] option (see
@secref["section-hyperlinks"]) causes each top-level section of a
document to be rendered as a separate HTML page.
To push sub-sections onto separate pages, use the @racket['toc] style
for the enclosing section (as started by @racket[title],
@racket[section], @racket[subsection], etc.) and use
@racket[local-table-of-contents] to generate hyperlinks to the
sub-sections.
Revising @filepath{cows.scrbl} from the previous section:
@codeblock|{
#lang scribble/manual
@title[#:style '(toc)]{Cows}
@local-table-of-contents[]
@section[#:tag "singing"]{Singing}
Wherever they go, it's a quite a show.
@section{Dancing}
See @secref["singing"].
}|
To run this example, remember to change @filepath{info.rkt} to add the
@racket['multi-page] style. You may also want to add a call to
@racket[table-of-contents] in @filepath{manual.scrbl}.
The difference between @racket[table-of-contents] and
@racket[local-table-of-contents] is that the latter is ignored for
Latex output.
When using @racket[local-table-of-contents], it often makes sense to
include introductory text before the call of
@racket[local-table-of-contents]. When the introductory text is less
important and when local table of contents is short, putting the
introductory text after the call of @racket[local-table-of-contents]
may be appropriate.

494
scribble-doc/scribblings/scribble/html.scrbl
View File

@ -1,494 +0,0 @@
#lang scribble/doc
@(require scribble/manual
scribble/core
scribble/eval
(only-meta-in 0 "utils.rkt")
(for-label (except-in racket/base #%top #%module-begin)
racket/contract/base
racket/string
scribble/html))
@(define html-eval (make-base-eval))
@interaction-eval[#:eval html-eval (require scribble/html)]
@interaction-eval[#:eval html-eval (require racket/string)]
@title[#:tag "html" #:style 'toc]{HTML Generation}
@defmodulelang[scribble/html]{The @racketmodname[scribble/html]
language provides a way to generate HTML that is different from
@racketmodname[scribble/base]. The @racketmodname[scribble/base]
approach involves describing a document that can be rendered to HTML,
Latex, or other formats. The @racketmodname[scribble/html] approach,
in contrast, treats the document content as HTML format plus escapes.}
Specifically, @racketmodname[scribble/html] is like
@racketmodname[scribble/text], but with the following changes:
@itemize[
@item{The @racketmodname[scribble/html/html],
@racketmodname[scribble/html/xml], and
@racketmodname[scribble/html/resource] are re-exported,
in addition to @racketmodname[scribble/text].}
@item{Free identifiers that end with @litchar{:} are implicitly
quoted as symbols.}
]
When @racketmodname[scribble/html] is used via @racket[require]
instead of @hash-lang[], then it does not change the printing of
values, and it does not include the bindings of @racket[racket/base].
The @racketmodname[scribble/html/resource],
@racketmodname[scribble/html/xml], and
@racketmodname[scribble/html/html] libraries provide forms for
generating HTML as strings to be output in the same way as
@racketmodname[scribble/text].
@local-table-of-contents[]
@; ----------------------------------------
@section[#:tag "html-html"]{Generating HTML Strings}
@defmodule[scribble/html/html]{The @racketmodname[scribble/html/html]
provides functions for HTML representations that render to string form
via @racket[output-xml].}
@defproc[(doctype [s (or/c string 'html 'xhtml)]) procedure?]{
Produces a value that @tech{XML-renders} as a DOCTYPE declaration.
@examples[#:eval html-eval
(output-xml (doctype "?"))
(output-xml (doctype 'html))
(regexp-split #rx"\n|((?<=\") (?=\"))"
(xml->string (doctype 'xhtml)))]}
@defproc[(xhtml [content outputable/c] ...) procedure?]{
Produces a value that @tech{XML-renders} as the given content wrapped
as XHTML.
@examples[#:eval html-eval
(regexp-split #rx"\n|((?<=\") (?=\"))"
(xml->string (xhtml "Hello")))]}
@(define-syntax-rule (def-tags tag ...)
@deftogether[(
@defproc[(tag [v outputable/c] (... ...)) procedure?] ...
)]{
Like @racket[element/not-empty], but with the symbolic form of the function
name added as the first argument.
@examples[#:eval html-eval
(output-xml (title "The Book"))]})
@(def-tags
html
head
title
style ; style info, which may include CDATA sections
script ; script statements, which may include CDATA sections
noscript ; alternate content container for non script-based rendering
frameset ; only one noframes element permitted per document
frame ; tiled window within frameset
iframe ; inline subwindow
noframes ; alternate content container for non frame-based rendering
body
div ; generic language/style container
p
h1
h2
h3
h4
h5
h6
ul ; Unordered list
ol ; Ordered (numbered) list
menu ; single column list (DEPRECATED)
dir ; multiple column list (DEPRECATED)
li ; list item
dl ; definition lists - dt for term, dd for its definition
dt
dd
address ; information on author
pre
blockquote
center ; center content
ins
del
a ; content is inline; except that anchors shouldn't be nested
span ; generic language/style container
bdo ; I18N BiDi over-ride
em ; emphasis
strong ; strong emphasis
dfn ; definitional
code ; program code
samp ; sample
kbd ; something user would type
var ; variable
cite ; citation
abbr ; abbreviation
acronym ; acronym
q ; inlined quote
sub ; subscript
sup ; superscript
tt ; fixed pitch font
i ; italic font
b ; bold font
big ; bigger font
small ; smaller font
u ; underline
s ; strike-through
strike ; strike-through
font ; local change to font
object ; embeded objects
applet ; Java applet
form ; forms shouldn't be nested
label ; text that belongs to a form control
select ; option selector
optgroup ; option group
option ; selectable choice
textarea ; multi-line text field
fieldset ; group form fields
legend ; fieldset label (one per fieldset)
button ; push button
table ; holds caption?, (col*|colgroup*), thead?, tfoot?, (tbody+|tr+)
caption ; caption text
thead ; header part, holds tr
tfoot ; footer part, holds tr
tbody ; body part, holds tr
colgroup ; column group, olds col
tr ; holds th or td
th ; header cell
td)
@(define-syntax-rule (def-tags/empty tag ...)
@deftogether[(
@defproc[(tag [v outputable/c] (... ...)) procedure?] ...
)]{
Like @racket[element], but with the symbolic form of the function
name added as the first argument.
@examples[#:eval html-eval
(output-xml (hr))]})
@(def-tags/empty
base meta link hr br basefont param img area input isindex col)
@(define-syntax-rule (def-entities ent ...)
@deftogether[(
@defthing[ent procedure?] ...
)]{
The result of @racket[(entity '_id)] for each @racket[_id].
@examples[#:eval html-eval
(output-xml nbsp)]})
@(def-entities
nbsp ndash mdash bull middot sdot lsquo rsquo sbquo ldquo rdquo bdquo
lang rang dagger Dagger plusmn deg)
@defproc[(script/inline [v outputable/c] ...) procedure?]{
Procedures a value that renders as an inline script.
@examples[#:eval html-eval
(output-xml (script/inline type: "text/javascript" "var x = 5;"))]}
@defproc[(style/inline [v outputable/c] ...) procedure?]{
Procedures a value that renders as an inline style sheet.
@examples[#:eval html-eval
(output-xml (style/inline type: "text/css"
".racket { font-size: xx-large; }"))]}
@; ----------------------------------------
@section[#:tag "html-xml"]{Generating XML Strings}
@defmodule[scribble/html/xml]{The @racketmodname[scribble/html/xml]
provides functions for XML representations that @deftech{XML-render} to string form
via @racket[output-xml] or @racket[xml->string].}
@defproc[(output-xml [content outputable/c] [port output-port? (current-output-port)])
void?]{
Renders @racket[content] in the same way as @racket[output], but using
the value of @racket[xml-writer] as the @tech{current writer} so that
special characters are escaped as needed.}
@defproc[(xml->string [content outputable/c]) string?]{
Renders @racket[content] to a string via @racket[output-xml].}
@defparam[xml-writer writer ((string? output-port? . -> . void))]{
A parameter for a function that is used with @racket[with-writer] by
@racket[output-xml]. The default value is a function that escapes
@litchar{&}, @litchar{<}, @litchar{>}, and @litchar{"} to entity form.}
@defproc[(make-element [tag symbol?]
[attrs (listof (cons/c symbol? outputable/c))]
[content outputable/c])
(and/c procedure outputable/c?)]{
Produces a value that @tech{XML-renders} as XML for the
given tag, attributes, and content.
When an attribute in @racket[attrs] is mapped to @racket[#f], then it
is skipped. When an attribute is mapped to @racket[#t], then it is
rendered as present, but without a value.
@examples[#:eval html-eval
(output-xml (make-element 'b '() '("Try" #\space "Racket")))
(output-xml (make-element 'a '((href . "http://racket-lang.org")) "Racket"))
(output-xml (make-element 'div '((class . "big") (overlay . #t)) "example"))
]}
@defproc[(element [tag symbol?] [attrs-and-content any/c] ...)
(and procedure outputable/c?)]{
Like @racket[make-element], but the list of @racket[attrs-and-content]
is parsed via @racket[attributes+body] to separate the attributes and
content.
@examples[#:eval html-eval
(output-xml (element 'b "Try" #\space "Racket"))
(output-xml (element 'a 'href: "http://racket-lang.org" "Racket"))
(output-xml (element 'div 'class: "big" 'overlay: #t "example"))
(require scribble/html)
(output-xml (element 'div class: "big" overlay: #t "example"))
]}
@defproc[(element/not-empty [tag symbol?] [attrs-and-content any/c] ...)
(and/c procedure? outputable/c)]{
Like @racket[element], but the result always renders with an separate
closing tag.
@examples[#:eval html-eval
(output-xml (element 'span))
(output-xml (element/not-empty 'span))
]}
@defproc[(attribute? [v any/c]) (or/c #f symbol?)]{
Returns a symbol without if @racket[v] is a symbol that ends with
@litchar{:}, @racket[#f] otherwise. When a symbol is returned, it is
the same as @racket[v], but without the trailing @litchar{:}.
@examples[#:eval html-eval
(attribute? 'a:)
(attribute? 'a)
(require scribble/html)
(attribute? a:)
]}
@defproc[(attributes+body [lst list?]) (values (listof (cons/c symbol? any/c))
list?)]{
Parses @racket[lst] into an association list mapping attributes to
list elements plus a list of remaining elements. The first
even-positioned (counting from 0) non-@racket[attribute?] element of
@racket[lst] is the start of the ``remaining elements'' list, while
each preceding even-positioned attribute is mapped in the association
list to the immediately following element of @racket[lst]. In the
association list, the trailing @litchar{:} is stripped for each
attribute.}
@defproc[(split-attributes+body [lst list?]) (values list? list?)]{
Like @racket[attributes+body], but produces a flat list (of
alternating attributes and value) instead of an association list as
the first result.}
@defproc[(literal [content any/c] ...) procedure?]{
Produces a value that @tech{XML-renders} without escapes
for special characters.
@examples[#:eval html-eval
(output-xml (literal "a->b"))
(output-xml "a->b")]}
@defproc[(entity [v (or/c exact-integer? symbol?)]) procedure?]{
Produces a value that @tech{XML-renders} as a numeric or
symbolic entity.
@examples[#:eval html-eval
(output-xml (entity 'gt))]}
@defproc[(comment [content outputable/c] ... [#:newlines? newlines? any/c #f])
procedure?]{
Produces a value that @tech{XML-renders} as a comment with
literal content. If @racket[newlines?] is true, then newlines are
inserted before and after the content.
@examples[#:eval html-eval
(output-xml (comment "testing" 1 2 3))]}
@defproc[(cdata [content outputable/c] ...
[#:newlines? newlines? any/c #t]
[#:line-pfx line-pfx any/c #f])
procedure?]{
Produces a value that @tech{XML-renders} as CDATA with
literal content. If @racket[newlines?] is true, then newlines are
inserted before and after the content. The @racket[line-pfx] value is
rendered before the CDATA opening and closing markers.
@examples[#:eval html-eval
(output-xml (cdata "testing" 1 2 3))]}
@defform[(define/provide-elements/empty tag-id ...)]{
Defines and exports @racket[tag-id] as a function that is like
@racket[element], but with @racket['tag-id] added as the first argument.}
@defform[(define/provide-elements/not-empty tag-id ...)]{
Defines and exports @racket[tag-id] as a function that is like
@racket[element/not-empty], but with @racket['_tag-id] added as the
first argument.}
@defform[(define/provide-entities entity-id ...)]{
Defines and exports @racket[entity-id] as the
result of @racket[(entity '_entity-id)].}
@; ----------------------------------------
@section[#:tag "html-resources"]{HTML Resources}
@defmodule[scribble/html/resource]
@defproc[(resource [path string?]
[renderer (or/c (path-string? . -> . any) #f)]
[#:exists exists (or/c 'delete-file #f) 'delete-file])
(and/c resource?
(->* () (outputable/c) -> string?))]{
Creates and returns a new @deftech{resource} value. Creating a
resource registers @racket[renderer] (if non-@racket[#f]) to be called when rendering is
initiated by @racket[render-all], while calling the result resource as
a function generates a URL for the resource.
For example, a typical use of @racket[resource] is to register the
generation of a CSS file, where the value produced by
@racket[resource] itself renders as the URL for the generated CSS
file. Another possible use of @racket[resource] is to generate an HTML
file, where the @racket[resource] result renders as the URL of the
generated HTML page.
The @racket[path] argument specifies the path of the output file,
relative to the working directory, indicating where the resource file
should be placed. Though @racket[url-roots], @racket[path] also
determines the ultimate URL. The @racket[path] string must be a
@litchar{/}-separated relative path with no @litchar{..}, @litchar{.},
or @litchar{//}. The @racket[path] string can end in @litchar{/}, in
which case @racket["index.html"] is effectively added to the string.
Using @racket[resource] with @racket[#f] as @racket[renderer] is
useful for converting a path to a URL according to @racket[url-roots].
The @racket[renderer] argument (when non-@racket[#f]) renders the resource, receiving the
path for the file to be created. The path provided to
@racket[renderer] will be different from @racket[path], because the
function is invoked in the target directory.
The resulting resource value is a function that returns the URL for
the resource. The function accepts an optional boolean; if a true
value is provided, the result is an absolute URL, instead of relative.
Note that the function can be used as a value for @racket[output],
which uses the resource value as a thunk (that renders as the relative
URL for the resource). The default relative resulting URL is, of
course, a value that depends on the currently rendered resource that
uses this value.
When @racket[renderer] is called by @racket[render-all], more
resources can be created while rendering; the newly created resources
will also be rendered, in turn, until no more new resources are
created.
If @racket[exists] is @racket['delete-file] and the target file exists
when @racket[renderer] is to be called, then the file is deleted
before @racket[renderer] is called.}
@defparam[url-roots roots (or/c #f
(listof (cons/c path-string?
(cons/c string?
(listof (or/c 'abs 'index))))))]{
A parameter that determines how resource paths are converted to URLs
for reference. A @racket[#f] value is equivalent to an empty list.
The parameter value is a mapping from path prefixes to URLs (actually,
any string). When two paths have the same prefix, links from one to
the other are relative (unless absolute links are requested); if they
have different prefixes, the full URL is used. The paths enclosed by
two root paths must be disjoint (e.g., the list must not include
both @racket["/colors"] and @racket["/colors/red"], but it can include
both @racket["/colors/red"] and @racket["/colors/blue"]).
If an item in the parameter's list includes @racket['abs], then a
site-local, absolute URL (i.e., a URL that starts with @litchar{/}) is
produced for references among files within the corresponding prefix.
If an item in the parameter's list includes @racket['index], then a
reference to a directory path is converted to a reference to
@filepath{index.html}, otherwise a reference to @filepath{index.html}
is converted to a directory path.}
@defproc[(resource? [v any/c]) boolean?]{
Returns @racket[#t] if @racket[v] is a procedure (that takes 0 or 1
arguments) produced by @racket[resource].}
@defproc[(render-all) void?]{
Generates all resources registered via @racket[resource].}
@defproc[(file-writer [content-writer (outputable/c output-port? . -> . any)]
[content outputable/c])
(path-string? . -> . any)]{
Produces a function that is useful as a @racket[_writer] argument to
@racket[resource]. Given a path, the produced function writes
@racket[content] to the path by passing @racket[content] and an output
port for the file to @racket[content-writer].}
@; ------------------------------------------------------------
@close-eval[html-eval]

4
scribble-doc/scribblings/scribble/inbox.css
View File

@ -1,4 +0,0 @@
.InBox {
padding: 0.2em;
border: 1px solid #000000;
}

2
scribble-doc/scribblings/scribble/inbox.tex
View File

@ -1,2 +0,0 @@
\newcommand{\InBox}[1]{\fbox{#1}}

14
scribble-doc/scribblings/scribble/info.rkt
View File

@ -1,14 +0,0 @@
#lang info
(define scribblings '(("scribble.scrbl" (multi-page) (racket-core -24))
("scribble-pp.scrbl" (multi-page) (tool))
("demo-s1.scrbl" (keep-style no-search) (omit-start))
("demo-m1.scrbl" (multi-page keep-style no-search) (omit-start))
("demo-s2.scrbl" (keep-style) (omit-start))
("demo-m2.scrbl" (multi-page keep-style) (omit-start))
("demo-manual-s1.scrbl" (keep-style no-search) (omit-start))
("demo-manual-m1.scrbl" (multi-page keep-style no-search) (omit-start))
("demo-manual-s2.scrbl" (keep-style) (omit-start))
("demo-manual-m2.scrbl" (multi-page keep-style) (omit-start))))

19
scribble-doc/scribblings/scribble/internals.scrbl
View File

@ -1,19 +0,0 @@
#lang scribble/manual
@(require "utils.rkt")
@title[#:tag "internals" #:style 'toc]{Low-Level Scribble API}
@local-table-of-contents[]
@include-section["layers.scrbl"]
@include-section["reader-internals.scrbl"]
@include-section["core.scrbl"]
@include-section["renderer.scrbl"]
@include-section["decode.scrbl"]
@include-section["doclang.scrbl"]
@include-section["docreader.scrbl"]
@include-section["xref.scrbl"]
@include-section["tag.scrbl"]
@include-section["blueboxes.scrbl"]
@include-section["config.scrbl"]

73
scribble-doc/scribblings/scribble/jfp.scrbl
View File

@ -1,73 +0,0 @@
#lang scribble/manual
@(require (except-in "utils.rkt" author) (for-label scribble/jfp))
@(define-syntax-rule (def base-author)
(begin
(require (for-label scribble/base))
(define base-author @racket[author])))
@(def base-author)
@title{JFP Paper Format}
@defmodulelang[scribble/jfp]{The @racketmodname[scribble/jfp]
language is like @racketmodname[scribble/base], but configured with
Latex style defaults to use the @filepath{jfp1.cls} class
file. The class file is not included with Scribble due to license
issues, but if the file is not manually installed into the
@racket[scribble/jfp] collections, then it is downloaded on demand to
@racket[(find-system-path 'addon-dir)].}
Latex output with @racketmodname[scribble/jfp] uses a main-document
version supplied to @racket[title] as the short-form document name (to
be used in page headers).
@defproc[(abstract [pre-content pre-content?] ...) block?]{
Generates a @tech{nested flow} for a paper abstract.}
@defform[(include-abstract module-path)]{
Similar to @racket[include-section], but incorporates the document in the
specified module as an abstract. The document must have no title or
sub-parts.}
@defproc[(author [name pre-content?] ...)
block?]{
A replacement for @base-author from @racketmodname[scribble/base].}
@defproc[((author/short [short-name pre-content?] ...) [long-name pre-content?] ...)
block?]{
Like @racket[author], but allows the short-form names (to be used in
page headers) to be specified separately from the long-form name.}
@deftogether[(
@defproc[(affiliation [place pre-content?] ...) element?]
@defproc[(affiliation-mark [mark pre-content?] ...) element?]
@defproc[(affiliation-sep) element?]
)]{
Use @racket[affiliation] within @racket[author] or the long-name part
of @racket[author/short] to specify affiliations after all authors.
If different authors have different affiliations, use
@racket[affiliation-mark] with a number after each author, and then
use @racket[affiliation-mark] before each different affiliation within
a single @racket[affiliation], using @racket[(affiliation-sep)] to
separate affiliations.}
Examples:
@codeblock|{
#lang scribble/jfp
@title{My First Love Story}
@((author/short "Romeo M. and Juliet C.")
"ROMEO" (affiliation-mark "1")
" and "
"JULIET" (affiliation-mark "2")
@affiliation[
"House Montague" (affiliation-mark "1")
(affiliation-sep)
"House Capulet" (affiliation-mark "2")])
}|

239
scribble-doc/scribblings/scribble/layers.scrbl
View File

@ -1,239 +0,0 @@
#lang scribble/doc
@(require scribble/manual scribble/bnf "utils.rkt")
@title[#:tag "layers"]{Scribble Layers}
Scribble is made of independently usable parts. For example, the
Scribble reader can be used in any situation that requires lots of
free-form text. You can also skip Scribble's special reader support,
and instead use the document-generation structure directly.
@; ----------------------------------------------------------------------
@section{Typical Composition}
A Scribble document normally starts
@racketmod[
scribble/manual
]
but it could also start
@racketmod[
scribble/base
]
or
@racketmod[
scribble/doc
]
The last one introduces the smallest number of typesetting bindings in
the document body. Using @racketmodname[scribble/base] after
@hash-lang[] is the same as using @racketmodname[scribble/doc] plus
@racket[(require scribble/base)], and using
@racketmodname[scribble/manual] after @hash-lang[] is the same as using
@racketmodname[scribble/doc] plus @racket[(require scribble/manual)].
Besides making the file a module, each of the @hash-lang[]
declarations selects the Scribble reader (instead of the usual Racket
reader), and it starts the body of the file in ``text'' mode. The
reader layer mostly leaves text alone, but @tech{@"@"-forms} escape
to S-expression mode.
A module written as
@verbatim[#:indent 2]|{
#lang scribble/doc
@(require scribble/manual)
@(define to-be "To Be")
@title{@|to-be| or Not @|to-be|}
@bold{That} is the question.
Whether 'tis nobler...
}|
reads as
@racketblock[
(module #,(nonterm "name") scribble/doc
(require scribble/manual)
"\n"
(define to-be "To Be") "\n"
"\n"
(title to-be " or Not " to-be) "\n"
"\n"
(bold "That") " is the question." "\n"
"Whether 'tis nobler..." "\n")
]
As shown in this example, the read result is a module whose content
mingles text and definitions. The @racketmodname[scribble/doc]
language lifts definitions, @racket[require]s, and @racket[provide]s
to the beginning of the module, while everything else is collected
into a document bound to the provided identifier @racket[doc]. That
is, the module is transformed to something like this:
@racketblock[
(module #,(nonterm "name") racket/base
(require scribble/decode
scribble/manual)
(define to-be "To Be")
(define doc
(decode
"\n" "\n" "\n"
(title to-be " or Not " to-be) "\n"
"\n"
(bold "That") " is the question." "\n"
"Whether 'tis nobler..." "\n"))
(provide doc))
]
The @racket[decode] function produces a @racket[part] structure
instance that represents the document. To build the @racket[part]
instance, it inspects its arguments to find a @racket[title-decl]
value created by @racket[title] to name the part, @racket[part-start]
values created by @racket[section] to designate sub-parts, etc.
A @racket[part] is the input to a rendering back-end, such as the HTML
renderer. All renderers recognize a fixed structure hierarchy: the
content of a part is a @defterm{flow}, which is a sequence of
@defterm{flow elements}, such as paragraphs and tables; a table, in
turn, consists of a list of list of flows; a paragraph is a list of
@defterm{elements}, which can be instances of the @racket[element]
structure type, plain strings, or certain special symbols.
The value bound to @racket[doc] in the example above is something like
@racketblock[
(make-part ....
(list "To Be" " or Not " "To Be") (code:comment "title")
....
(make-flow
(list
(make-paragraph
(list (make-element 'bold (list "That"))
" is the question." "\n"
"Whether " 'rsquo "tis nobler..."))))
....)
]
Notice that the @litchar{'} in the input's @litchar{'tis} has turned
into @racket['rsquo] (rendered as a curly apostrophe). The conversion to use
@racket['rsquo] was performed by @racket[decode] via
@racket[decode-flow] via @racket[decode-paragraph] via
@racket[decode-content] via @racket[decode-string].
In contrast, @racket[(make-element 'bold (list "That"))] was produced
by the @racket[bold] function. The @racket[decode] operation is a
function, not a syntactic form, and so @racket[bold] has control over
its argument before @racket[decode] sees the result. Also, decoding
traverses only immediate string arguments.
As it turns out, @racket[bold] also decodes its argument, because the
@racket[bold] function is implemented as
@racketblock[
(define (bold . strs)
(make-element 'bold (decode-content strs)))
]
The @racket[verbatim] function, however, does not decode its content,
and instead typesets its text arguments directly.
A document module can construct elements directly using
@racket[make-element], but normally functions like @racket[bold] and
@racket[verbatim] are used to construct them. In particular, the
@racketmodname[scribble/manual] library provides many functions and
forms to typeset elements and flow elements.
The @racket[part] structure hierarchy includes built-in element types
for setting hyperlink targets and references. Again, this machinery is
normally packaged into higher-level functions and forms, such as
@racket[secref], @racket[defproc], and @racket[racket].
@; ----------------------------------------------------------------------
@section{Layer Roadmap}
Working roughly from the bottom up, the Scribble layers are:
@itemize[
@item{@racketmodname[scribble/reader]: A reader that extends the
syntax of Racket with @tech{@"@"-forms} for conveniently embedding a
mixin of text and escapes. See @secref["reader"].}
@item{@racketmodname[scribble/core]: A set of document datatypes
and utilities that define the basic layout and processing of a
document. For example, the @racket[part] datatype is defined in
this layer. See @secref["core"].}
@item{@racketmodname[scribble/base-render] with
@racketmodname[scribble/html-render],
@racketmodname[scribble/latex-render], or
@racketmodname[scribble/text-render]: A base renderer and
mixins that generate documents in various formats from
instances of the @racketmodname[scribble/struct] datatypes. See
@secref["renderer"].}
@item{@racketmodname[scribble/decode]: Processes a stream of text,
section-start markers, etc. to produce instances of the
@racketmodname[scribble/core] datatypes. See
@secref["decode"].}
@item{@racketmodname[scribble/doclang]: A language to be used for the
initial import of a module; processes the module top level
through @racketmodname[scribble/decode], and otherwise provides
all of @racketmodname[racket/base]. See @secref["doclang"].}
@item{@racketmodname[scribble/doc]: A language that combines
@racketmodname[scribble/reader] with
@racketmodname[scribble/doclang]. See @secref["docreader"].}
@item{@racketmodname[scribble/base]: A library of basic document
operators---such as @racket[title], @racket[section], and
@racket[secref]---for use with @racketmodname[scribble/decode]
and a renderer. This library name also can be used as a
language, where it combines @racketmodname[scribble/doc] with
the exports of @racketmodname[scribble/base]. See
@secref["base"].}
@item{@racketmodname[scribble/racket]: A library of functions for
typesetting Racket code. See @secref["scheme"]. These functions
are not normally used directly, but instead used through
@racketmodname[scribble/manual].}
@item{@racketmodname[scribble/manual]: A library of functions for
writing Racket documentation; re-exports
@racketmodname[scribble/base]. Also, the
@racketmodname[scribble/manual-struct] library provides types
for index-entry descriptions created by functions in
@racketmodname[scribble/manual]. See @secref["manual"].}
@item{@racketmodname[scribble/eval]: A library of functions for
evaluating code at document-build time, especially for showing
examples. See @secref["eval"].}
@item{@racketmodname[scribble/bnf]: A library of support functions
for writing grammars. See @secref["bnf"].}
@item{@racketmodname[scribble/xref]: A library of support functions
for using cross-reference information, typically after a
document is rendered (e.g., to search). See @secref["xref"].}
@item{@racketmodname[scribble/text]: A language that uses
@racketmodname[scribble/reader] preprocessing text files.}
]
The @exec{scribble} command-line utility generates output with a
specified renderer. More specifically, the executable installs a
renderer, loads the modules specified on the command line, extracts
the @racket[doc] export of each module (which must be an instance of
@racket[part]), and renders each---potentially with links that span
documents.

97
scribble-doc/scribblings/scribble/lncs.scrbl
View File

@ -1,97 +0,0 @@
#lang scribble/manual
@(require (except-in "utils.rkt" author)
(except-in (for-label scribble/lncs/lang) #%module-begin))
@(define-syntax-rule (def base-author)
(begin
(require (for-label scribble/base))
(define base-author @racket[author])))
@(def base-author)
@title{LNCS Paper Format}
@defmodulelang[scribble/lncs #:use-sources (scribble/lncs/lang)]{
The @racketmodname[scribble/lncs]
language is like @racketmodname[scribble/base], but configured with
Latex style defaults to use the @filepath{llncs.cls} class
file. The class file is not included with Scribble due to license issues,
but if the file is not manually installed into the
@racket[scribble/lncs] collection, then it is downloaded on demand to
@racket[(find-system-path 'addon-dir)].}
@defproc[(abstract [pre-content pre-content?] ...) block?]{
Generates a @tech{nested flow} for a paper abstract.}
@defform[(include-abstract module-path)]{
Similar to @racket[include-section], but incorporates the document in the
specified module as an abstract. The document must have no title or
sub-parts.}
@defform/subs[#:literals (author)
(authors auth ...)
([auth (author pre-content-expr ...)
(author #:inst str-expr pre-content-expr ...)])
#:contracts ([pre-content-expr pre-content?]
[str-expr string?])]{
A replacement for @base-author from @racketmodname[scribble/base].
The @racket[#:inst] should be a number that matches up to one of the
arguments to @racket[institutes].
}
@defidform[author]{For use only in @racket[authors].}
@defform[#:literals (institute)
(institutes (institute pre-content-expr ...) ...)
#:contracts ([pre-content-expr pre-content?])]{
The @racket[pre-content-expr]s are used as the institutions of the authors.
}
@defidform[institute]{For use only in @racket[institutes].}
@defform[(email pre-content-expr ...)]{
Specifies an email address; must be used inside @racket[institute].
}
@section{Example}
Here is an example of a paper written in the LNCS format:
@margin-note{For more randomly generated papers, see SCIgen:
@url["http://pdos.csail.mit.edu/scigen"]}
@codeblock[#:keep-lang-line? #t]|{
#lang scribble/lncs
@authors[@author[#:inst "1"]{Lauritz Darragh}
@author[#:inst "2"]{Nikolaj Kyran}
@author[#:inst "2"]{Kirsten Gormlaith}
@author[#:inst "2"]{Tamaz Adrian}]
@institutes[
@institute["University of Southeast Boston"
@linebreak[]
@email|{darragh@cs.seboston.edu}|]
@institute["University of Albion"
@linebreak[]
@email|{{nkyran,gorm,tamaz}@cs.albion.ac.uk}|]]
@title{Arak: Low-Energy, Interposable Theory}
@abstract{The implications of client-server symmetries have been
far-reaching and pervasive. Given the current status of
constant-time theory, mathematicians daringly desire the synthesis
of rasterization, which embodies the essential principles of
algorithms. In this work, we describe a client-server tool for
investigating flip-flop gates (Arak), verifying that the
producer-consumer problem can be made homogeneous, secure, and
wireless.}
}|

4
scribble-doc/scribblings/scribble/lp-ex-doc.scrbl
View File

@ -1,4 +0,0 @@
#lang scribble/doc
@(require scribble/lp-include)
@lp-include["lp-ex.rkt"]

18
scribble-doc/scribblings/scribble/lp-ex.rkt
View File

@ -1,18 +0,0 @@
#lang scribble/lp2
@(require scribble/manual)
Literate programs have chunks of code, like this one:
@chunk[<f>
(define (f x)
<fs-body>)]
and this one:
@chunk[<fs-body>
(* x x)]
that, when assembled, produce a complete program, in this case:
@racketblock[(define (f x)
(* x x))]

4
scribble-doc/scribblings/scribble/lp.css
View File

@ -1,4 +0,0 @@
.LPBoxed {
padding: 1ex;
border: 1px solid #000000;
}

136
scribble-doc/scribblings/scribble/lp.scrbl
View File

@ -1,136 +0,0 @@
#lang scribble/doc
@(require scribble/manual scribble/core scribble/html-properties
scribble/latex-properties
racket/runtime-path
racket/file
"utils.rkt"
(prefix-in lp-ex: "lp-ex-doc.scrbl")
(for-label scribble/lp-include scribble/lp))
@title[#:tag "lp"
#:style (make-style #f
(list (make-css-addition "lp.css")
(make-tex-addition "lp.tex")))
]{Literate Programming}
Programs written using @racketmodname[scribble/lp2] are simultaneously
two things: a program and a document describing the program:
@itemlist[
@item{When the program is run, all of the @racket[chunk] expressions
are collected and stitched together into a program, and the
rest of the module is discarded.}
@item{When the program is provided to Scribble---or used through
@racket[include-section] in another Scribble document with a
@racket[(submod ... doc)] module path---the entire contents of
the module are treated like an ordinary Scribble document,
where @racket[chunk]s are typeset in a manner similar to
@racket[codeblock].}
]
@(define-runtime-path lp-ex "lp-ex.rkt")
For example, consider this program:
@(codeblock (file->string lp-ex))
When this file is @racket[require]d in the normal manner, it defines a
function @racket[f] that squares its argument, and the documentation
is ignored. When it is rendered as a Scribble document, the output
looks like this:
@(make-nested-flow
(make-style "LPBoxed" null)
(part-blocks lp-ex:doc))
@; ------------------------------------------------------------
@section{@racketmodname[scribble/lp2] Language}
@defmodulelang[scribble/lp2 #:use-sources (scribble/lp)]{The
@racketmodname[scribble/lp] language provides core support for
literate programming. It is read like a @racketmodname[scribble/base]
program, but its bindings extend @racketmodname[racket/base] with two
forms: @racket[chunk] and @racket[CHUNK].}
More precisely, a module in @racketmodname[scribble/lp2] has its
@racketmodname[racket/base]-like content in a @racketidfont{doc}
submodule, which is recognized by tools such as @exec{raco scribble}.
The content of the @racket[chunk] and @racket[CHUNK] forms is
stitched together as the immediate content of the module.
The @racket[chunk] and @racket[CHUNK] content is discovered by first
@racket[expand]ing the module as written. The content is collected
into a new module, and then the original module content is placed into
a @racket[doc] submodule that is expanded (so that the content is
effectively re-expanded). The @racketidfont{doc} submodule is declared
with @racket[module*].
@history[#:added "1.8"
#:changed "1.17" @elem{Declared the @racketidfont{doc} submodule with
@racket[module*] instead of @racket[module].}]
@defform[(chunk id form ...)]{
Introduces a chunk, binding @racket[id] for use in other
chunks. Normally, @racket[id] starts with @litchar{<} and ends with
@litchar{>}.
When running the enclosing program, only the code inside the
chunks is run; the rest is ignored.
If @racket[id] is @racketidfont{<*>}, then this chunk is
used as the main chunk in the file. If @racketidfont{<*>}
is never used, then the first chunk in the file is treated
as the main chunk. If some chunk is not referenced from
the main chunk (possibly indirectly via other chunks that
the main chunk references), then it is not included in the
program and thus is not run.
The @racket[form]s are typeset using @racket[racketblock], so
@racket[code:comment], etc., can be used to adjust the output.
Those output-adjusting forms are stripped from each @racket[form]
for running the program.
@history[#:changed "1.17" @elem{Strip @racket[code:comment], etc., for running.}]}
@defform[(CHUNK id form ...)]{
Like @racket[chunk], but typesets with @racket[RACKETBLOCK], so @racket[unsyntax]
can be used normally in each @racket[form]. To escape,
use @racket[UNSYNTAX].
}
@; ------------------------------------------------------------
@section{@racketmodname[scribble/lp] Language}
@defmodulelang[scribble/lp]{Programs written using the older
@racketmodname[scribble/lp] language are similar to
@racketmodname[scribble/lp2] programs, except that the module cannot
be provided directly to Scribble. Instead, the document content must be
extracted using @racket[lp-include].}
The @racketmodname[scribble/lp] language effectively binds only
@racket[chunk] and @racket[CHUNK], while all other bindings for
documentation are taken from the context where @racket[lp-include] is
used.
@; ------------------------------------------------------------
@section{@racketmodname[scribble/lp-include] Module}
@defmodule[scribble/lp-include]{The
@racketmodname[scribble/lp-include] library is normally used within a
Scribble document---that is, a module that starts with something like
@racket[#, @hash-lang[] @racketmodname[scribble/base]] or @racket[#, @hash-lang[]
@racketmodname[scribble/manual]], instead of @racket[#, @hash-lang[] @racketmodname[racket]].}
@defform[(lp-include filename)]{
Includes the source of @racket[filename] as the typeset version of the literate
program.
}

3
scribble-doc/scribblings/scribble/lp.tex
View File

@ -1,3 +0,0 @@
\usepackage{framed}
\newenvironment{LPBoxed}{\begin{framed}}{\end{framed}}

8
scribble-doc/scribblings/scribble/manual-stub.scrbl
View File

@ -1,8 +0,0 @@
#lang scribble/manual
@(require "utils.rkt" (for-label scribble/sigplan))
@title{Racket Manual Format}
The @racketmodname[scribble/manual] language is a major component of
Scribble, and it is documented in its own chapter:
@secref["plt-manuals"].

2185
scribble-doc/scribblings/scribble/manual.scrbl
View File

File diff suppressed because it is too large Load Diff

25
scribble-doc/scribblings/scribble/plt.scrbl
View File

@ -1,25 +0,0 @@
#lang scribble/manual
@(require "utils.rkt")
@title[#:tag "plt-manuals" #:style 'toc]{Scribbling Documentation}
The @racketmodname[scribble/manual] language and associated libraries
provide extensive support for documenting Racket libraries. The
most significant aspect of support for documentation is the way that
source-code bindings are connected to documentation sites through the
module namespace---a connection that is facilitated by the fact that
Scribble documents are themselves modules that reside in the same
namespace. @Secref["how-to-doc"] provides an introduction to using
Scribble for documentation, and the remaining sections document the
relevant libraries and APIs in detail.
@local-table-of-contents[]
@include-section["how-to.scrbl"]
@include-section["style.scrbl"]
@include-section["manual.scrbl"]
@include-section["scheme.scrbl"]
@include-section["examples.scrbl"]
@include-section["srcdoc.scrbl"]
@include-section["bnf.scrbl"]
@include-section["compat.scrbl"]

335
scribble-doc/scribblings/scribble/reader-internals.scrbl
View File

@ -1,335 +0,0 @@
#lang scribble/doc
@(require scribble/manual scribble/bnf scribble/eval "utils.rkt"
(for-syntax racket/base)
(for-label (only-in scribble/reader
use-at-readtable)))
@(define read-eval (make-base-eval))
@(interaction-eval #:eval read-eval (require (for-syntax racket/base)))
@title[#:tag "reader-internals"]{@"@" Reader Internals}
@;--------------------------------------------------------------------
@section{Using the @"@" Reader}
You can use the reader via Racket's @racketfont{#reader} form:
@racketblock[
@#,racketfont|{
#reader scribble/reader @foo{This is free-form text!}
}|]
or use the @racket[at-exp] meta-language as described in
@secref["at-exp-lang"].
Note that the Scribble reader reads @tech{@"@"-forms} as S-expressions. This
means that it is up to you to give meanings for these expressions in
the usual way: use Racket functions, define your functions, or require
functions. For example, typing the above into @exec{racket} is likely
going to produce a ``reference to undefined identifier'' error, unless
@racket[foo] is defined. You can use @racket[string-append] instead,
or you can define @racket[foo] as a function (with variable arity).
A common use of the Scribble @"@"-reader is when using Scribble as a
documentation system for producing manuals. In this case, the manual
text is likely to start with
@racketmod[scribble/doc]
which installs the @"@" reader starting in ``text mode,'' wraps the
file content afterward into a Racket module where many useful Racket
and documentation related functions are available, and parses the body
into a document using @racketmodname[scribble/decode]. See
@secref["docreader"] for more information.
Another way to use the reader is to use the @racket[use-at-readtable]
function to switch the current readtable to a readtable that parses
@tech{@"@"-forms}. You can do this in a single command line:
@commandline{racket -ile scribble/reader "(use-at-readtable)"}
@;--------------------------------------------------------------------
@section{Syntax Properties}
The Scribble reader attaches properties to syntax objects. These
properties might be useful in some rare situations.
Forms that Scribble reads are marked with a @racket['scribble]
property, and a value of a list of three elements: the first is
@racket['form], the second is the number of items that were read from
the datum part, and the third is the number of items in the body part
(strings, sub-forms, and escapes). In both cases, a @racket[0] means
an empty datum/body part, and @racket[#f] means that the corresponding
part was omitted. If the form has neither parts, the property is not
attached to the result. This property can be used to give different
meanings to expressions from the datum and the body parts, for
example, implicitly quoted keywords:
@; FIXME: a bit of code duplication here
@def+int[
#:eval read-eval
(define-syntax (foo stx)
(let ([p (syntax-property stx 'scribble)])
(printf ">>> ~s\n" (syntax->datum stx))
(syntax-case stx ()
[(_ x ...)
(and (pair? p) (eq? (car p) 'form) (even? (cadr p)))
(let loop ([n (/ (cadr p) 2)]
[as '()]
[xs (syntax->list #'(x ...))])
(if (zero? n)
(with-syntax ([attrs (reverse as)]
[(x ...) xs])
#'(list 'foo `attrs x ...))
(loop (sub1 n)
(cons (with-syntax ([key (car xs)]
[val (cadr xs)])
#'(key ,val))
as)
(cddr xs))))])))
(eval:alts
(code:line
@#,tt["@foo[x 1 y (* 2 3)]{blah}"])
;; Unfortunately, expressions are preserved by `def+int'
;; using `quote', not `quote-syntax' (which would create all sorts
;; or binding trouble), so we manually re-attach the property:
(eval (syntax-property #'@foo[x 1 y (* 2 3)]{blah}
'scribble '(form 4 1))))
]
In addition, the Scribble parser uses syntax properties to mark syntax
items that are not physically in the original source --- indentation
spaces and newlines. Both of these will have a @racket['scribble]
property; an indentation string of spaces will have
@racket['indentation] as the value of the property, and a newline will
have a @racket['(newline S)] value where @racket[S] is the original
newline string including spaces that precede and follow it (which
includes the indentation for the following item). This can be used to
implement a verbatim environment: drop indentation strings, and use
the original source strings instead of the single-newline string. Here
is an example of this.
@; FIXME: a bit of code duplication here
@def+int[
#:eval read-eval
(define-syntax (verb stx)
(syntax-case stx ()
[(_ cmd item ...)
#`(cmd
#,@(let loop ([items (syntax->list #'(item ...))])
(if (null? items)
'()
(let* ([fst (car items)]
[prop (syntax-property fst 'scribble)]
[rst (loop (cdr items))])
(cond [(eq? prop 'indentation) rst]
[(not (and (pair? prop)
(eq? (car prop) 'newline)))
(cons fst rst)]
[else (cons (datum->syntax-object
fst (cadr prop) fst)
rst)])))))]))
(eval:alts
(code:line
@#,tt["@verb[string-append]{"]
@#,tt[" foo"]
@#,tt[" bar"]
@#,tt["}"])
@verb[string-append]{
foo
bar
})
]
@;--------------------------------------------------------------------
@section[#:tag "at-exp-lang"]{Adding @"@"-expressions to a Language}
@defmodulelang[at-exp]{The @racketmodname[at-exp] language installs
@seclink["reader"]{@"@"-reader} support in the readtable used to read
a module, and then chains to the reader of
another language that is specified immediately after
@racketmodname[at-exp].}
For example, @racket[@#,hash-lang[] at-exp racket/base] adds @"@"-reader
support to @racket[racket/base], so that
@racketmod[
at-exp racket/base
(define (greet who) @#,elem{@tt["@"]@racket[string-append]@racketparenfont["{"]@racketvalfont{Hello, }@tt["@|"]@racket[who]@tt["|"]@racketvalfont{.}@racketparenfont["}"]})
(greet "friend")]
reports @racket["Hello, friend."].
In addition to configuring the reader for a module body,
@racketmodname[at-exp] attaches a run-time configuration annotation to
the module, so that it if it used as the main module, the
@racket[current-read-interaction] parameter is adjusted to use the
@seclink["reader"]{@"@"-reader} readtable extension.
@history[#:changed "1.2" @elem{Added @racket[current-read-interaction]
run-time configuration.}]
@;--------------------------------------------------------------------
@section{Interface}
@defmodule[scribble/reader]{The @racketmodname[scribble/reader] module
provides direct Scribble reader functionality for advanced needs.}
@; The `with-scribble-read' trick below shadows `read' and
@; `read-syntax' with for-label bindings from the Scribble reader
@(define-syntax with-scribble-read
(syntax-rules ()
[(_)
(...
(begin
(require (for-label scribble/reader))
@; *** Start reader-import section ***
@deftogether[(
@defproc[(read [in input-port? (current-input-port)]) any]{}
@defproc[(read-syntax [source-name any/c (object-name in)]
[in input-port? (current-input-port)])
(or/c syntax? eof-object?)]
)]{
Implements the Scribble reader using the readtable produced by
@racketblock[(make-at-readtable #:command-readtable 'dynamic
#:datum-readtable 'dynamic)]
@history[#:changed "1.1" @elem{Changed to use @racket['dynamic] for the command and datum readtables.}]}
@deftogether[(
@defproc[(read-inside [in input-port? (current-input-port)]) any]{}
@defproc[(read-syntax-inside [source-name any/c (object-name in)]
[in input-port? (current-input-port)]
[#:command-char command-char char? #\@])
(or/c syntax? eof-object?)]
)]{
Like @racket[read] and @racket[read-syntax], but starting as if
inside a @litchar["@{"]...@litchar["}"] to return a (syntactic) list,
which is useful for implementing languages that are textual by default.
The given @racket[command-char] is used to customize the readtable
used by the reader, effectively passing it along to @racket[make-at-readtable].
@history[#:changed "1.1" @elem{Changed to use @racket['dynamic] for the command and datum readtables.}]
}
@defproc[(make-at-readtable
[#:readtable readtable readtable? (current-readtable)]
[#:command-char command-char char? #\@]
[#:command-readtable command-readtable (or/c readtable? 'dynamic) readtable]
[#:datum-readtable datum-readtable
(or/c readtable?
boolean?
(readtable? . -> . readtable?)
'dynamic)
#t]
[#:syntax-post-processor syntax-post-proc
(syntax? . -> . syntax?)
values])
readtable?]{
Constructs an @"@"-readtable. The keyword arguments can customize the
resulting reader in several ways:
@itemize[
@item{@racket[readtable] --- a readtable to base the @"@"-readtable
on.}
@item{@racket[command-char] --- the character used for @tech{@"@"-forms}.}
@item{@racket[command-readtable] --- determines the readtable that is
extended for reading the command part of an @tech{@"@"-form}:
@itemlist[
@item{a readtable --- extended to make @litchar{|} a delimiter
instead of a symbol-quoting character}
@item{@racket['dynamic] --- extends @racket[(current-readtable)]
at the point where a command is parsed to make @litchar{|} a
delimiter}
]}
@item{@racket[datum-readtable] --- the readtable used for
reading the datum part of an @tech{@"@"-form}:
@itemlist[
@item{@racket[#t] --- uses the constructed @"@"-readtable itself}
@item{a readtable --- uses the given readtable}
@item{a readtable-to-readtable function --- called to construct a readtable
from the generated @"@"-readtable}
@item{@racket['dynamic] --- uses @racket[(current-readtable)] at the
point where the datum part is parsed}
]
The idea is that you may want to have completely
different uses for the datum part, for example, introducing a
convenient @litchar{key=val} syntax for attributes.}
@item{@racket[syntax-post-proc] --- function that is applied on
each resulting syntax value after it has been parsed (but before it
is wrapped quoting punctuations). You can use this to further
control uses of @tech{@"@"-forms}, for example, making the command be the
head of a list:
@racketblock[
(use-at-readtable
#:syntax-post-processor
(lambda (stx)
(syntax-case stx ()
[(cmd rest ...) #'(list 'cmd rest ...)]
[_else (error "@ forms must have a body")])))
]}
]
@history[#:changed "1.1" @elem{Added @racket[#:command-readtable] and
the @racket['dynamic] option for @racket[#:datum-readtable].}]}
@defproc[(make-at-reader [#:syntax? syntax? #t] [#:inside? inside? #f] ...)
procedure?]{
Constructs a variant of a @"@"-readtable. The arguments are the same
as in @racket[make-at-readtable], with two more that determine the
kind of reader function that will be created: @racket[syntax?] chooses
between a @racket[read]- or @racket[read-syntax]-like function, and
@racket[inside?] chooses a plain reader or an @racketid[-inside]
variant.
The resulting function has a different contract and action based on
these inputs. The expected inputs are as in @racket[read] or
@racket[read-syntax] depending on @racket[syntax?]; the function will
read a single expression or, if @racket[inside?] is true, the whole
input; it will return a syntactic list of expressions rather than a
single one in this case.
Note that @racket[syntax?] defaults to @racket[#t], as this is the
more expected common case when you're dealing with concrete-syntax
reading.
Note that if @racket[syntax?] is true, the @racket[read]-like function
is constructed by simply converting a syntax result back into a datum.}
@defproc[(use-at-readtable ...) void?]{
Passes all arguments to @racket[make-at-readtable], and installs the
resulting readtable using @racket[current-readtable]. It also enables
line counting for the current input-port via @racket[port-count-lines!].
This is mostly useful for playing with the Scribble syntax on the REPL.}
@; *** End reader-import section ***
))]))
@with-scribble-read[]
@; --------------------------------------------------
@(close-eval read-eval)

742
scribble-doc/scribblings/scribble/reader.scrbl
View File

@ -1,742 +0,0 @@
#lang scribble/doc
@(require scribble/manual scribble/bnf scribble/eval "utils.rkt"
(for-syntax racket/base)
(for-label (only-in scribble/reader
use-at-readtable)))
@(define read-eval (make-base-eval))
@(interaction-eval #:eval read-eval (require (for-syntax racket/base)))
@(define (at-exp-racket)
@racket[#, @hash-lang[] #, @racketmodname[at-exp] #, @racketidfont{racket}])
@title[#:tag "reader"]{@"@" Syntax}
The Scribble @"@" notation is designed to be a convenient facility for
free-form text in Racket code, where ``@"@"'' was chosen as one of the
least-used characters in existing Racket code. An @"@"-expression is
simply an S-expression in disguise.
Typically, @"@" notation is enabled through
@racketmodname[scribble/base] or similar languages, but you can also
add @"@" notation to an S-expression-based language using the
@racketmodname[at-exp] meta-language. For example,
@verbatim[#:indent 2]|{
#lang at-exp racket
(define v '@op{str})
}|
is equivalent to
@racketmod[
racket
(define v '(op "str"))
]
Using @at-exp-racket[] is probably the easiest way to try the examples
in this chapter.
@;--------------------------------------------------------------------
@section{The Scribble Syntax at a Glance}
To review @secref["how-to:reader"], the concrete syntax of @deftech{@"@"-forms}
is roughly
@racketblock[
@#,BNF-seq[@litchar["@"]
@nonterm{cmd}
@litchar{[} @kleenestar{@nonterm{datum}} @litchar{]}
@litchar["{"] @kleenestar{@nonterm{text-body}} @litchar["}"]]
]
where all three parts after @litchar["@"] are optional, but at least
one should be present. (Spaces are not allowed between the
three parts.) Roughly, a form matching the above grammar is read as
@racketblock[
(@#,nonterm{cmd} @#,kleenestar{@nonterm{datum}} @#,kleenestar{@nonterm{parsed-body}})
]
where @nonterm{parsed-body} is the translation of each
@nonterm{text-body} in the input. Thus, the initial @nonterm{cmd}
determines the Racket code that the input is translated into. The
common case is when @nonterm{cmd} is a Racket identifier, which reads
as a plain Racket form, with datum arguments and/or string arguments.
Here is one example:
@scribble-examples|==={
@foo{blah blah blah}
}===|
The example shows how an input syntax is read as Racket syntax, not
what it evaluates to. If you want to see the translation of an example
into S-expression form, add a quote in front of it in a
@at-exp-racket[] module. For example, running
@verbatim[#:indent 2]|{
#lang at-exp racket
'@foo{blah blah blah}
}|
in DrRacket prints the output
@nested[#:style 'inset]{@racketresult[(foo "blah blah blah")]}
while omitting the quote
@verbatim[#:indent 2]|{
#lang at-exp racket
@foo{blah blah blah}
}|
triggers a syntax error because @racket[foo] is not bound, and
@verbatim[#:indent 2]|{
#lang at-exp racket
(define (foo str) (printf "He wrote ~s.\n" str))
@foo{blah blah blah}
}|
prints the output
@nested[#:style 'inset]{@racketoutput{He wrote "blah blah blah".}}
Here are more examples of @tech{@"@"-forms}:
@scribble-examples|==={
@foo{blah "blah" (`blah'?)}
@foo[1 2]{3 4}
@foo[1 2 3 4]
@foo[#:width 2]{blah blah}
@foo{blah blah
yada yada}
@foo{
blah blah
yada yada
}
}===|
As seen in the last example, multiple lines and the newlines that
separate them are parsed to multiple Racket strings. More generally,
a @nonterm{text-body} is made of text, newlines, and nested
@tech{@"@"-forms}, where the syntax for @tech{@"@"-forms} is the same whether it's
in a @nonterm{text-body} context as in a Racket context. A
@nonterm{text-body} that isn't an @tech{@"@"-form} is converted to a string
expression for its @nonterm{parsed-body}; newlines and following
indentations are converted to @racket["\n"] and all-space string
expressions.
@scribble-examples|==={
@foo{bar @baz{3}
blah}
@foo{@b{@u[3] @u{4}}
blah}
@C{while (*(p++))
*p = '\n';}
}===|
The command part of an @tech{@"@"-form} is optional as well. In that case,
the @tech{@"@"-form} is read as a list, which usually counts as a function
application, but it also useful when quoted with the usual Racket
@racket[quote]:
@scribble-examples|==={
@{blah blah}
@{blah @[3]}
'@{foo
bar
baz}
}===|
Finally, we can also drop the datum and text parts, which leaves us with
only the command---which is read as is, not within a parenthesized
form. This is not useful when reading Racket code, but it can be used
inside a text block to escape a Racket identifier. A vertical bar
(@litchar{|}) can be used to delimit the escaped identifier when
needed.
@scribble-examples|==={
@foo
@{blah @foo blah}
@{blah @foo: blah}
@{blah @|foo|: blah}
}===|
Actually, the command part can be any Racket expression (that does not
start with @litchar["["], @litchar["{"], or @litchar["|"]), which is
particularly useful with such escapes since they can be used with any
expression.
@scribble-examples|==={
@foo{(+ 1 2) -> @(+ 1 2)!}
@foo{A @"string" escape}
}===|
Note that an escaped Racket string is merged with the surrounding text
as a special case. This is useful if you want to use the special
characters in your string, but escaping braces are not necessary if
they are balanced.
@scribble-examples|==={
@foo{eli@"@"barzilay.org}
@foo{A @"{" begins a block}
@C{while (*(p++)) {
*p = '\n';
}}
}===|
In some cases, a text contains many literal @"@"s, which can be
cumbersome to quote individually. For such case, braces have an
alternative syntax: A block of text can begin with a
``@litchar["|{"]'' and terminated accordingly with a
``@litchar["}|"]''. Furthermore, any nested @tech{@"@"-forms} must begin
with a ``@litchar["|@"]''.
@scribble-examples|==={
@foo|{bar}@{baz}|
@foo|{bar |@x{X} baz}|
@foo|{bar |@x|{@}| baz}|
}===|
In cases when even this is not convenient enough, punctuation
characters can be added between the @litchar{|} and the braces and the
@"@" in nested forms. (The punctuation is mirrored for parentheses
and @litchar{<>}s.) With this extension, @tech{@"@"-form} syntax can be used as a
``here string'' replacement.
@scribble-examples|==={
@foo|--{bar}@|{baz}--|
@foo|<<{bar}@|{baz}>>|
}===|
On the flip side of this is, how can an @"@" sign be used in Racket
code? This is almost never an issue, because Racket strings and
characters are still read the same, and @litchar["@"] is set as a
non-terminating reader macro so it can be used in Racket identifiers
anywhere except in the first character of an identifier. When
@litchar["@"] must appear as the first character of an identifier, you
must quote the identifier just like other non-standard characters in
normal S-expression syntax: with a backslash or with vertical bars.
@scribble-examples|==={
(define \@email "foo@bar.com")
(define |@atchar| #\@)
}===|
Note that spaces are not allowed before a @litchar{[} or a
@litchar["{"], or they will be part of the following text (or Racket
code). (More on using braces in body texts below.)
@scribble-examples|==={
@foo{bar @baz[2 3] {4 5}}
}===|
Finally, remember that @tech{@"@"-forms} are just an alternate form of
S-expressions. Identifiers still get their meaning, as in any
Racket code, through the lexical context in which they appear.
Specifically, when the above @tech{@"@"-form} appears in a Racket expression
context, the lexical environment must provide bindings for
@racket[foo] as a procedure or a macro; it can be defined, required,
or bound locally (with @racket[let], for example).
@; FIXME: unfortunate code duplication
@interaction[
(eval:alts
(let* ([formatter (lambda (fmt)
(lambda args (format fmt (apply string-append args))))]
[bf (formatter "*~a*")]
[it (formatter "/~a/")]
[ul (formatter "_~a_")]
[text string-append])
#,(tt "@text{@it{Note}: @bf{This is @ul{not} a pipe}.}"))
(let* ([formatter (lambda (fmt)
(lambda args (format fmt (apply string-append args))))]
[bf (formatter "*~a*")]
[it (formatter "/~a/")]
[ul (formatter "_~a_")]
[text string-append])
@text{@it{Note}: @bf{This is @ul{not} a pipe}.}))
]
@;--------------------------------------------------------------------
@section{The Command Part}
Besides being a Racket identifier, the @nonterm{cmd} part of an
@tech{@"@"-form} can have Racket punctuation prefixes, which will end up
wrapping the @italic{whole} expression.
@scribble-examples|==={
@`',@foo{blah}
@#`#'#,@foo{blah}
}===|
When writing Racket code, this means that @litchar|{@`',@foo{blah}}|
is exactly the same as @litchar|{`@',@foo{blah}}| and
@litchar|{`',@@foo{blah}}|, but unlike the latter two, the first
construct can appear in body texts with the same meaning, whereas the
other two would not work (see below).
After the optional punctuation prefix, the @nonterm{cmd} itself is not
limited to identifiers; it can be @italic{any} Racket expression.
@scribble-examples|==={
@(lambda (x) x){blah}
@`(unquote foo){blah}
}===|
In addition, the command can be omitted altogether, which will omit it
from the translation, resulting in an S-expression that usually
contains, say, just strings:
@scribble-examples|==={
@{foo bar
baz}
@'{foo bar
baz}
}===|
If the command part begins with a @litchar{;} (with no newline between
the @litchar["@"] and the @litchar{;}), then the construct is a
comment. There are two comment forms, one for arbitrary-text and
possibly nested comments, and another one for line comments:
@racketblock[
@#,BNF-seq[@litchar["@;{"] @kleenestar{@nonterm{any}} @litchar["}"]]
@#,BNF-seq[@litchar["@;"] @kleenestar{@nonterm{anything-else-without-newline}}]
]
In the first form, the commented body must still parse correctly; see
the description of the body syntax below. In the second form, all
text from the @litchar["@;"] to the end of the line @italic{and} all
following spaces (or tabs) are part of the comment (similar to
@litchar{%} comments in TeX).
@scribble-examples|==={
@foo{bar @; comment
baz@;
blah}
}===|
Tip: if you use an editor in some Scheme mode without support for
@tech{@"@"-forms}, balanced comments can be confusing, since the open brace
looks commented out, and the closing one isn't. In such cases it is
useful to ``comment'' out the closing brace too:
@verbatim[#:indent 2]|==={
@;{
...
;}
}===|
so the editor does not treat the file as having unbalanced
parentheses.
If only the @nonterm{cmd} part of an @tech{@"@"-form} is specified, then the
result is the command part only, without an extra set of parenthesis.
This makes it suitable for Racket escapes in body texts. (More on this
below, in the description of the body part.)
@scribble-examples|==={
@foo{x @y z}
@foo{x @(* y 2) z}
@{@foo bar}
}===|
Finally, note that there are currently no special rules for using
@litchar["@"] in the command itself, which can lead to things like:
@scribble-examples|==={
@@foo{bar}{baz}
}===|
@;--------------------------------------------------------------------
@section{The Datum Part}
The datum part can contains arbitrary Racket expressions, which
are simply stacked before the body text arguments:
@scribble-examples|==={
@foo[1 (* 2 3)]{bar}
@foo[@bar{...}]{blah}
}===|
The body part can still be omitted, which is essentially an
alternative syntax for plain (non-textual) S-expressions:
@scribble-examples|==={
@foo[bar]
@foo{bar @f[x] baz}
}===|
The datum part can be empty, which makes no difference, except when
the body is omitted. It is more common, however, to use an empty body
for the same purpose.
@scribble-examples|==={
@foo[]{bar}
@foo[]
@foo
@foo{}
}===|
The most common use of the datum part is for Racket forms that expect
keyword-value arguments that precede the body of text arguments.
@scribble-examples|==={
@foo[#:style 'big]{bar}
}===|
@;--------------------------------------------------------------------
@section{The Body Part}
The syntax of the body part is intended to be as convenient as
possible for free text. It can contain almost any text---the only
characters with special meaning is @litchar["@"] for sub-@tech{@"@"-forms},
and @litchar["}"] for the end of the text. In addition, a
@litchar["{"] is allowed as part of the text, and it makes the
matching @litchar["}"] be part of the text too---so balanced braces
are valid text.
@scribble-examples|==={
@foo{f{o}o}
@foo{{{}}{}}
}===|
As described above, the text turns to a sequence of string arguments
for the resulting form. Spaces at the beginning and end of lines are
discarded, and newlines turn to individual @racket["\n"] strings
(i.e., they are not merged with other body parts); see also the
information about newlines and indentation below. Spaces are
@italic{not} discarded if they appear after the open @litchar["{"]
(before the closing @litchar["}"]) when there is also text that
follows (precedes) it; specifically, they are preserved in a
single-line body.
@scribble-examples|==={
@foo{bar}
@foo{ bar }
@foo[1]{ bar }
}===|
If @litchar["@"] appears in a body, then it is interpreted as Racket
code, which means that the @"@"-reader is applied recursively, and the
resulting syntax appears as part of the S-expression, among other
string contents.
@scribble-examples|==={
@foo{a @bar{b} c}
}===|
If the nested @"@" construct has only a command---no body or datum
parts---it will not appear in a subform. Given that the command part
can be any Racket expression, this makes @"@" a general escape to
arbitrary Racket code.
@scribble-examples|==={
@foo{a @bar c}
@foo{a @(bar 2) c}
}===|
This is particularly useful with strings, which can be used to include
arbitrary text.
@scribble-examples|==={
@foo{A @"}" marks the end}
}===|
Note that the escaped string is (intentionally) merged with the rest
of the text. This works for @litchar["@"] too:
@scribble-examples|==={
@foo{The prefix: @"@".}
@foo{@"@x{y}" --> (x "y")}
}===|
@;--------------------------------------------------------------------
@subsection[#:tag "alt-body-syntax"]{Alternative Body Syntax}
In addition to the above, there is an alternative syntax for the body,
one that specifies a new marker for its end: use @litchar["|{"] for
the opening marker to have the text terminated by a @litchar["}|"].
@scribble-examples|==={
@foo|{...}|
@foo|{"}" follows "{"}|
@foo|{Nesting |{is}| ok}|
}===|
This applies to sub-@tech{@"@"-forms} too---the @litchar["@"] must be
prefixed with a @litchar{|}:
@scribble-examples|==={
@foo|{Maze
|@bar{is}
Life!}|
@t|{In |@i|{sub|@"@"s}| too}|
}===|
Note that the subform uses its own delimiters, @litchar{{...}} or
@litchar{|{...}|}. This means that you can copy and paste Scribble
text with @tech{@"@"-forms} freely, just prefix the @litchar["@"] if the
immediate surrounding text has a prefix.
For even better control, you can add characters in the opening
delimiter, between the @litchar{|} and the @litchar["{"].
Characters that are put there (non alphanumeric ASCII characters only,
excluding @litchar["{"] and @litchar["@"]) should also be used for
sub-@tech{@"@"-forms}, and the end-of-body marker should have these characters
in reverse order with paren-like characters (@litchar{(},
@litchar{[}, @litchar{<}) mirrored.
@scribble-examples|==={
@foo|<<<{@x{foo} |@{bar}|.}>>>|
@foo|!!{X |!!@b{Y}...}!!|
}===|
Finally, remember that you can use an expression escape with a Racket
string for confusing situations. This works well when you only need
to quote short pieces, and the above works well when you have larger
multi-line body texts.
@;--------------------------------------------------------------------
@subsection{Racket Expression Escapes}
In some cases, you may want to use a Racket identifier (or a number or
a boolean etc.) in a position that touches the following text; in
these situations you should surround the escaped Racket expression by
a pair of @litchar{|} characters. The text inside the bars is
parsed as a Racket expression.
@scribble-examples|==={
@foo{foo@bar.}
@foo{foo@|bar|.}
@foo{foo@3.}
@foo{foo@|3|.}
}===|
This form is a generic Racket expression escape, there is no body text
or datum part when you use this form.
@scribble-examples|==={
@foo{foo@|(f 1)|{bar}}
@foo{foo@|bar|[1]{baz}}
}===|
This works for string expressions too, but note that unlike the above,
the string is (intentionally) not merged with the rest of the text:
@scribble-examples|==={
@foo{x@"y"z}
@foo{x@|"y"|z}
}===|
Expression escapes also work with @italic{any} number of expressions,
@scribble-examples|==={
@foo{x@|1 (+ 2 3) 4|y}
@foo{x@|*
*|y}
}===|
It seems that @litchar["@||"] has no purpose---but remember that these escapes
are never merged with the surrounding text, which can be useful when
you want to control the sub expressions in the form.
@scribble-examples|==={
@foo{Alice@||Bob@|
|Carol}
}===|
Note that @litchar["@|{...}|"] can be parsed as either an escape expression or
as the Racket command part of an @tech{@"@"-form}. The latter is used in this case
(since there is little point in Racket code that uses braces.
@scribble-examples|==={
@|{blah}|
}===|
@;--------------------------------------------------------------------
@subsection{Comments}
As noted above, there are two kinds of @tech{@"@"-form} comments: @litchar|{@;{...}}| is
a (nestable) comment for a whole body of text (following the same
rules for @tech{@"@"-forms}), and @litchar|{@;...}| is a line-comment.
@scribble-examples|==={
@foo{First line@;{there is still a
newline here;}
Second line}
}===|
One useful property of line-comments is that they continue to the end
of the line @italic{and} all following spaces (or tabs). Using this,
you can get further control of the subforms.
@scribble-examples|==={
@foo{A long @;
single-@;
string arg.}
}===|
Note how this is different from using @litchar["@||"]s in that strings
around it are not merged.
@;--------------------------------------------------------------------
@subsection{Spaces, Newlines, and Indentation}
The @tech{@"@"-form} syntax treats spaces and newlines in a special way is
meant to be sensible for dealing with text. As mentioned above,
spaces at the beginning and end of body lines are discarded, except
for spaces between a @litchar["{"] and text, or between text and a
@litchar["}"].
@scribble-examples|==={
@foo{bar}
@foo{ bar }
@foo{ bar
baz }
}===|
A single newline that follows an open brace or precedes a closing
brace is discarded, unless there are only newlines in the body; other
newlines are read as a @racket["\n"] string
@scribble-examples|==={
@foo{bar
}
@foo{
bar
}
@foo{
bar
}
@foo{
bar
baz
}
@foo{
}
@foo{
}
@foo{ bar
baz }
}===|
Spaces at the beginning of body lines do not appear in the resulting
S-expressions, but the column of each line is noticed, and all-space
indentation strings are added so the result has the same indentation.
A indentation string is added to each line according to its distance
from the leftmost syntax object (except for empty lines). (Note: if
you try these examples on a Racket REPL, you should be aware that
the reader does not know about the ``@litchar{> }'' prompt.)
@scribble-examples|==={
@foo{
bar
baz
blah
}
@foo{
begin
x++;
end}
@foo{
a
b
c}
}===|
If the first string came from the opening @litchar["{"] line, it is
not prepended with an indentation (but it can affect the leftmost
syntax object used for indentation). This makes sense when formatting
structured code as well as text (see the last example in the following
block).
@scribble-examples|==={
@foo{bar
baz
bbb}
@foo{ bar
baz
bbb}
@foo{bar
baz
bbb}
@foo{ bar
baz
bbb}
@foo{ bar
baz
bbb}
@text{Some @b{bold
text}, and
more text.}
}===|
Note that each @"@"-form is parsed to an S-expression that has its own
indentation. This means that Scribble source can be indented like
code, but if indentation matters then you may need to apply
indentation of the outer item to all lines of the inner one. For
example, in
@litchar/lines|==={
@code{
begin
i = 1, r = 1
@bold{while i < n do
r *= i++
done}
end
}
}===|
a formatter will need to apply the 2-space indentation to the
rendering of the @racket[bold] body.
Note that to get a first-line text to be counted as a leftmost line,
line and column accounting should be on for the input port
(@racket[use-at-readtable] turns them on for the current input port).
Without this,
@litchar/lines|==={
@foo{x1
x2
x3}
}===|
will not have 2-space indentations in the parsed S-expression if
source accounting is not on, but
@litchar/lines|==={
@foo{x1
x2
x3}
}===|
will (due to the last line). Pay attention to this, as it can be a
problem with Racket code, for example:
@litchar/lines|==={
@code{(define (foo x)
(+ x 1))}
}===|
For rare situations where spaces at the beginning (or end) of lines
matter, you can begin (or end) a line with a @litchar["@||"].
@scribble-examples|==={
@foo{
@|| bar @||
@|| baz}
}===|
@; --------------------------------------------------
@(close-eval read-eval)

474
scribble-doc/scribblings/scribble/renderer.scrbl
View File

@ -1,474 +0,0 @@
#lang scribble/doc
@(require scribble/manual
"utils.rkt"
(for-label racket/class
scribble/render
scribble/xref))
@(define-syntax-rule (defmodule/local lib . content)
(begin
(define-syntax-rule (intro)
(begin
(require (for-label lib))
(defmodule lib)
. content))
(intro)))
@(begin
(define-syntax-rule (def-html-render-mixin id mid)
(begin
(require (for-label scribble/html-render))
(define id @racket[render-mixin])
(define mid @racket[render-multi-mixin])))
(def-html-render-mixin html:render-mixin html:render-multi-mixin))
@(begin
(define-syntax-rule (def-latex-render-mixin id)
(begin
(require (for-label scribble/latex-render))
(define id @racket[render-mixin])))
(def-latex-render-mixin latex:render-mixin))
@title[#:tag "renderer"]{Renderers}
A renderer is an object that provides four main methods:
@racket[traverse], @racket[collect], @racket[resolve], and
@racketidfont{render}. Each method corresponds to a pass described in
@secref["core"], and they are chained together by the @racket[render]
function to render a document.
@section{Rendering Driver}
@defmodule[scribble/render]
@defproc[(render [docs (listof part?)]
[names (listof path-string?)]
[#:render-mixin render-mixin (class? . -> . class?) @#,html:render-mixin]
[#:dest-dir dest-dir (or/c #f path-string?) #f]
[#:helper-file-prefix helper-file-prefix (or/c #f string?) #f]
[#:prefix-file prefix-file (or/c #f path-string?) #f]
[#:style-file style-file (or/c #f path-string?) #f]
[#:style-extra-files style-extra-files (listof path-string?) #f]
[#:extra-files extra-files (listof path-string?) #f]
[#:image-preferences image-preferences (listof (or/c 'ps 'pdf 'png 'svg 'gif)) null]
[#:xrefs xrefs (listof xref?) null]
[#:info-in-files info-in-files (listof path-string?) null]
[#:info-out-file info-out-file (or/c #f path-string?) #f]
[#:redirect redirect (or/c #f string?) #f]
[#:redirect-main redirect-main (or/c #f string?) #f]
[#:directory-depth directory-depth exact-nonnegative-integer? 0]
[#:quiet? quiet? any/c #t]
[#:warn-undefined? warn-undefined? any/c (not quiet?)])
void?]{
Renders the given @racket[docs], each with an output name derived from
the corresponding element of @racket[names]. A directory path (if any)
for a name in @racket[names] is discarded, and the file suffix is
replaced (if any) with a suitable suffix for the output format.
The @racket[render-mixin] argument determines the output format. By
default, it is @html:render-mixin from @racketmodname[scribble/html-render].
The @racket[dest-dir] argument determines the output directory, which
is created using @racket[make-directory*] if it is non-@racket[#f] and
does not exist already.
The @racket[helper-file-prefix], @racket[prefix-file],
@racket[style-file], @racket[style-extra-files], and
@racket[extra-files] arguments are passed on to the @racket[render%]
constructor.
The @racket[image-preferences] argument specified preferred formats
for image files and conversion, where formats listed earlier in the
list are more preferred. The renderer specified by
@racket[render-mixin] may not support all of the formats listed in
@racket[image-preferences].
The @racket[xrefs] argument provides extra cross-reference information
to be used during the documents' @tech{resolve pass}. The
@racket[info-in-files] arguments supply additional cross-reference
information in serialized form. When the @racket[info-out-file]
argument is not @racket[#f], cross-reference information for the
rendered documents is written in serialized for to the specified file.
The @racket[redirect] and @racket[redirect-main] arguments correspond
to the @racket[set-external-tag-path] and
@racket[set-external-root-url] methods of @|html:render-mixin| from
@racketmodname[scribble/html-render], so they should be
non-@racket[#f] only for HTML rendering.
The @racket[directory-depth] arguments correspond to the
@racket[set-directory-depth] method of @|html:render-multi-mixin|.
If @racket[quiet?] is a false value, output-file information is
written to the current output port.
If @racket[warn-undefined?] is a true value, then references to
missing cross-reference targets trigger a warning message on the
current error port.
@history[#:changed "1.4" @elem{Added the @racket[#:image-preferences] argument.}]}
@section{Base Renderer}
@defmodule[scribble/base-render]{The
@racketmodname[scribble/base-render] module provides @racket[render%],
which implements the core of a renderer. This rendering class must be
refined with a mixin from @racketmodname[scribble/text-render],
@racketmodname[scribble/markdown-render], or
@racketmodname[scribble/html-render], or
@racketmodname[scribble/latex-render].}
The mixin structure is meant to support document-specific extensions
to the renderers. For example, the @exec{scribble} command-line tool
might, in the future, extract rendering mixins from a document module
(in addition to the document proper).
See the @filepath{base-render.rkt} source for more information about
the methods of the renderer. Documents built with higher layers, such
as @racketmodname[scribble/manual], generally do not call the render
object's methods directly.
@definterface[render<%> ()]{
@defmethod[(traverse [srcs (listof part?)]
[dests (listof path-string?)])
(and/c hash? immutable?)]{
Performs the @techlink{traverse pass}, producing a hash table that
contains the replacements for and @racket[traverse-block]s and
@racket[traverse-elements]s. See @method[render<%> render] for
information on the @racket[dests] argument.}
@defmethod[(collect [srcs (listof part?)]
[dests (listof path-string?)]
[fp (and/c hash? immutable?)]
[demand (tag? collect-info? . -> . any/c) (lambda (_tag _ci) #f)])
collect-info?]{
Performs the @techlink{collect pass}. See @method[render<%> render] for
information on the @racket[dests] arguments. The @racket[fp] argument
is a result from the @method[render<%> traverse] method.
The @racket[demand] argument supplies external tag mappings on demand.
When the @racket[collect-info] result is later used to find a mapping
for a tag and no mapping is already available, @racket[demand] is
called with the tag and the @racket[collect-info]. The @racket[demand]
function returns true to indicate when it adds information to the
@racket[collect-info] so that the lookup should be tried again; the
@racket[demand] function should return @racket[#f] if it does not
extend @racket[collect-info].}
@defmethod[(resolve [srcs (listof part?)]
[dests (listof path-string?)]
[ci collect-info?])
resolve-info?]{
Performs the @techlink{resolve pass}. See @method[render<%> render] for
information on the @racket[dests] argument. The @racket[ci] argument
is a result from the @method[render<%> collect] method.}
@defmethod[(render [srcs (listof part?)]
[dests (listof path-string?)]
[ri resolve-info?])
void?]{
Produces the final output. The @racket[ri] argument is a result from
the @method[render<%> render] method.
The @racket[dests] provide names of files for Latex or single-file
HTML output, or names of sub-directories for multi-file HTML output.
If the @racket[dests] are relative, they're relative to the current
directory; normally, they should indicates a path within the
@racket[_dest-dir] supplied on initialization of the @racket[render%]
object.}
@defmethod[(serialize-info [ri resolve-info?])
any/c]{
Serializes the collected info in @racket[ri].}
@defmethod[(serialize-infos [ri resolve-info?]
[count exact-positive-integer?]
[doc part?])
list?]{
Like @method[render<%> serialize-info], but produces @racket[count] results
that together have the same information as produced by
@method[render<%> serialize-info]. The structure of @racket[doc] is used to
drive the partitioning (on the assumption that @racket[ri] is derived
from @racket[doc]).}
@defmethod[(deserialize-info [v any/c]
[ci collect-info?]
[#:root root-path (or/c path-string? false/c) #f])
void?]{
Adds the deserialized form of @racket[v] to @racket[ci].
If @racket[root-path] is not @racket[#f], then file paths that are
recorded in @racket[ci] as relative to an instantiation-supplied
@racket[root-path] are deserialized as relative instead to the given
@racket[root-path].}
@defmethod[(get-defined [ci collect-info?]) (listof tag?)]{
Returns a list of tags that were defined within the documents
represented by @racket[ci].}
@defmethod[(get-defineds [ci collect-info?]
[count exact-positive-integer?]
[doc part?])
(listof (listof tag?))]{
Analogous to @method[render<%> serialize-infos]: returns a list of
tags for each of @racket[count] partitions of the result of
@method[render<%> get-defined], using the structure of @racket[doc] to
drive the partitioning.}
@defmethod[(get-external [ri resolve-info?]) (listof tag?)]{
Returns a list of tags that were referenced but not defined within the
documents represented by @racket[ri] (though possibly found in
cross-reference information transferred to @racket[ri] via
@racket[xref-transfer-info]).}
@defmethod[(get-undefined [ri resolve-info?]) (listof tag?)]{
Returns a list of tags that were referenced by the resolved documents
with no target found either in the resolved documents represented by
@racket[ri] or cross-reference information transferred to @racket[ri]
via @racket[xref-transfer-info].
If multiple tags were referenced via @racket[resolve-search] and a
target was found for any of the tags using the same dependency key,
then no tag in the set is included in the list of undefined tags.}
}
@defclass[render% object% (render<%>)]{
Represents a renderer.
@defconstructor[([dest-dir path-string?]
[refer-to-existing-files any/c #f]
[root-path (or/c path-string? #f) #f]
[prefix-file (or/c path-string? #f) #f]
[style-file (or/c path-string? #f) #f]
[style-extra-files (listof path-string?) null]
[extra-files (listof path-string?) null]
[image-preferences (listof (or/c 'ps 'pdf 'png 'svg 'gif)) null])]{
Creates a renderer whose output will go to @racket[dest-dir]. For
example, @racket[dest-dir] could name the directory containing the
output Latex file, the HTML file for a single-file output, or the
output sub-directory for multi-file HTML output.
If @racket[refer-to-existing-files] is true, then when a document
refers to external files, such as an image or a style file, then the
file is referenced from its source location instead of copied to the
document destination.
If @racket[root-path] is not @racket[#f], it is normally the same as
@racket[dest-dir] or a parent of @racket[dest-dir]. It causes
cross-reference information to record destination files relative to
@racket[root-path]; when cross-reference information is serialized, it
can be deserialized via @method[render<%> deserialize-info] with a
different root path (indicating that the destination files have
moved).
The @racket[prefix-file], @racket[style-file], and
@racket[style-extra-files] arguments set files that control output
styles in a formal-specific way; see @secref["config-style"] for more
information.
The @racket[extra-files] argument names files to be copied to the
output location, such as image files or extra configuration files.
The @racket[image-preferences] argument specified preferred formats
for image files and conversion, where formats listed earlier in the
list are more preferred. The renderer may not support all of the
formats listed in @racket[image-preferences].
@history[#:changed "1.4" @elem{Added the @racket[image-preferences]
initialization argument.}]}}
@; ----------------------------------------
@section{Text Renderer}
@defmodule/local[scribble/text-render]{
@defmixin[render-mixin (render<%>) ()]{
Specializes a @racket[render<%>] class for generating plain text.}}
@; ----------------------------------------
@section{Markdown Renderer}
@defmodule/local[scribble/markdown-render]{
@defmixin[render-mixin (render<%>) ()]{
Specializes a @racket[render<%>] class for generating Markdown text.
Code blocks are marked using the
@hyperlink["http://github.github.com/github-flavored-markdown/"
"Github convention"] @verbatim{```racket} so that they are lexed and
formatted as Racket code.}}
@; ----------------------------------------
@section{HTML Renderer}
@defmodule/local[scribble/html-render]{
@defmixin[render-mixin (render<%>) ()]{
@defconstructor/auto-super[([search-box? boolean? #f])]{
Specializes a @racket[render<%>] class for generating
HTML output. The arguments are the same as
@racket[render<%>], except for the addition of
@racket[search-box].
If @racket[search-box?] is @racket[#t] and the document
is created with @racket[scribble/manual], then it will be
rendered with a search box, similar to this page. Note
that the @racket[search-box?] argument does not create
the search page itself. Rather, it passes the search
query to whatever page is located at
@tt{search/index.html}. The query is passed as an HTTP
query string in the @tt{q} field.}
@defmethod[(set-external-tag-path [url string?]) void?]{
Configures the renderer to redirect links to external documents via
@racket[url], adding a @tt{tag} query element to the end of the
URL that contains the Base64-encoded, @racket[print]ed, serialized
original tag (in the sense of @racket[link-element]) for the link.
If the link is based on a cross-reference entry that has a
document-identifying string (see @racket[load-xref] and its
@racket[#:doc-id] argument), the document identifier is added as a
@tt{doc} query element, and a path to the target within the
document is added as a @tt{rel} query element.}
@defmethod[(set-external-root-url [url string?]) void?]{
Configures the renderer to redirect links to documents installed in
the distribution's documentation directory to the given URL, using the
URL as a replacement to the path of the distribution's document
directory.}
}
@defmixin[render-multi-mixin (render<%>) ()]{
Further specializes a rendering class produced by
@racket[render-mixin] for generating multiple HTML
files.
@defmethod[(set-directory-depth [depth exact-nonnegative-integer?]) void?]{
Sets the depth of directory structure used when rendering parts that
are own their own pages. A value of @racket[0] is treated the same as
@racket[1].}
}
}
@; ----------------------------------------
@section{Latex Renderer}
@defmodule/local[scribble/latex-render]{
@defmixin[render-mixin (render<%>) ()]{
Specializes a @racket[render<%>] class for generating Latex input.}}
@defparam[extra-character-conversions convs (-> char? (or/c string? #f))]{
Function that maps (special) characters to strings corresponding to the Latex
code that should be used to render them. This function should return false for
any character it does not know how to handle.
Scribble already converts many special characters to the proper Latex
commands. This parameter should be used in case you need characters it does not
support yet.
}
@; ----------------------------------------
@section{PDF Renderer}
@defmodule/local[scribble/pdf-render]{
@defmixin[render-mixin (render<%>) ()]{
Specializes a @racket[render<%>] class for generating PDF output via
Latex, building on @|latex:render-mixin| from @racketmodname[scribble/latex-render].}}
@; ----------------------------------------
@section{Contract (Blue boxes) Renderer}
@defmodule/local[scribble/contract-render]{
@defmixin[override-render-mixin-multi (render<%>) ()]{
Overrides the @method[render<%> render] method of
given renderer to record the content of the
blue boxes (generated by @racket[defproc], @racket[defform], etc)
that appear in the document.
@defmethod[#:mode override
(render [srcs (listof part?)]
[dests (listof path?)]
[ri render-info?])
void?]{
In addition to doing whatever the @racket[super] method
does, also save the content of the blue boxes (rendered
via a @racketmodname[scribble/text-render] renderer).
It saves this information in three pieces in a file
inside the @racket[dests] directories called
@filepath{blueboxes.rktd}. The first piece is
a single line containing a (decimal, ASCII) number. That number
is the number of bytes that the second piece of information
occupies in the file. The second piece of information
is a @racket[hash] that maps @racket[tag?] values to
a list of offsets and line numbers that follow the hash table.
For example, if the @racket[hash] maps
@racket['(def ((lib "x/main.rkt") abcdef))] to
@racket['((10 . 3))], then that means that the documentation
for the @racket[abcdef] export from the @racket[x] collection
starts 10 bytes after the end of the hash table and continues for
@racket[3] lines. Multiple elements in the list mean that that
@racket[tag?] has multiple blue boxes and each shows where one
of the boxes appears in the file.
}}
@defmixin[override-render-mixin-single (render<%>) ()]{
Just like @racket[override-render-mixin-multi], except
it saves the resulting files in a different place.
@defmethod[#:mode override
(render [srcs (listof part?)]
[dests (listof path?)]
[ri render-info?])
void?]{
Just like @method[override-render-mixin-multi render], except
that it saves the file @filepath{blueboxes.rktd} in
the same directory where each @racket[dests] element resides.
}}
}

8
scribble-doc/scribblings/scribble/report.scrbl
View File

@ -1,8 +0,0 @@
#lang scribble/manual
@(require "utils.rkt")
@title{Report Format}
@defmodulelang[scribble/report]{The @racketmodname[scribble/report]
language is like @racketmodname[scribble/book], but configured with
Latex style defaults to use the standard @tt{report} class.}

212
scribble-doc/scribblings/scribble/running.scrbl
View File

@ -1,212 +0,0 @@
#lang scribble/manual
@(require "utils.rkt"
scribble/bnf
(for-label setup/xref))
@(define fn (italic "fn"))
@title[#:tag "running"]{Running @exec{scribble}}
The @exec{scribble} command-line tool (also available as @as-index{@exec{raco
scribble}}) runs a Scribble document and renders it to a specific
format. Select a format with one of the following flags, where the
output name @|fn| is by default the document source name without
its file suffix:
@itemlist[
@item{@DFlag{html} --- a single HTML page @filepath{@|fn|.html},
plus CSS sources and needed image files; this mode is the
default if no format is specified}
@item{@DFlag{htmls} --- multiple HTML pages (and associated files) in
a @filepath{@|fn|} directory, starting with
@filepath{@|fn|/index.html}}
@item{@DFlag{html-tree} @nonterm{n} --- HTML pages in a directory
tree up to @nonterm{n} layers deep; a tree of depth @exec{0} is
equivalent to using @DFlag{html}, and a tree of depth @exec{1}
is equivalent to using @DFlag{htmls}}
@item{@DFlag{latex} --- LaTeX source @filepath{@|fn|.tex}, plus
any needed additional files (such as non-standard class files)
needed to run @exec{latex} or @exec{pdflatex}}
@item{@DFlag{pdf} --- PDF @filepath{@|fn|.pdf} that is generated
via @exec{pdflatex}}
@item{@DFlag{dvipdf} --- PDF @filepath{@|fn|.pdf} that is generated
via @exec{latex}, @exec{dvips}, and @exec{pstopdf}}
@item{@DFlag{latex-section} @nonterm{n} --- LaTeX source
@filepath{@|fn|.tex} plus additional @filepath{.tex} files to
be included in the enclosing document's preamble, where the
enclosing document must use the UTF-8 input encoding and T1
font encoding; use @tt{1} for @nonterm{n} to make the rendered
document a section, @tt{2} for a subsection, etc.}
@item{@DFlag{text} --- plain text in a single file
@filepath{@|fn|.txt}, with non-ASCII content encoded as UTF-8}
@item{@DFlag{markdown} --- Markdown text in a single file
@filepath{@|fn|.md}, with non-ASCII content encoded as UTF-8}
]
Use @DFlag{dest-name} to specify a @|fn| other than the default name,
but only when a single source file is provided. Use the @DFlag{dest}
flag to specify a destination directory (for any number of source
files). Use @DFlag{dest-base} to add a prefix to the name of each
support file that is generated or copied to the destination.
After all flags, provide one or more document sources, where each
source declares a module. The module should either have a @racket[doc]
@tech[#:doc '(lib "scribblings/reference/reference.scrbl")]{submodule}
that exports @racket[doc] as a @racket[part], or it should directly
export @racket[doc] as a @racket[part]. (The submodule is tried first,
and the main module is not directly loaded or evaluated if the
submodule can be loaded on its own.)
When multiple documents are rendered at the same time, cross-reference
information in one document is visible to the other documents. See
@secref["xref-flags"] for information on references that cross
documents that are built separately.
@history[#:changed "1.4" @elem{Added @DFlag{dvipdf}.}]
@section{Extra and Format-Specific Files}
Use the @DFlag{style} flag to specify a format-specific file to adjust
the output style file for certain formats. For HTML (single-page or
multi-page) output, the style file should be a CSS file that is
applied after all other CSS files, and that may therefore override
some style properties. For Latex (or PDF) output, the style file
should be a @filepath{.tex} file that can redefine Latex commands.
When a particular Scribble function needs particular CSS or Latex
support, however, a better option is to use a @racket[css-addition] or
@racket[tex-addition] style property so that the support is included
automatically; see @secref["config"] for more information.
In rare cases, use the @DFlag{style} flag to specify a format-specific
base style file. For HTML (single-page or multi-page) output, the
style file should be a CSS file to substitute for
@filepath{scribble.css} in the @filepath{scribble} collection. For
Latex (or PDF) output, the style file should be a @filepath{.tex} file
to substitute for @filepath{scribble.tex} in the @filepath{scribble}
collection. The @DFlag{style} flag is rarely useful, because the
content of @filepath{scribble.css} or @filepath{scribble.tex} is
weakly specified; replacements must define all of the same styles, and
the set of styles can change across versions of Racket.
Use @DFlag{prefix} to specify an alternate format-specific start of
the output file. For HTML output, the starting file specifies the
@tt{DOCTYPE} declaration of each output HTML file as a substitute for
@filepath{scribble-prefix.html} in the @filepath{scribble}
collection. For Latex (or PDF) output (but not Latex-section output), the starting file specifies
the @ltx{documentclass} declaration and initial @ltx{usepackage}
declarations as a substitute for @filepath{scribble-prefix.tex} in the
@filepath{scribble} collection. See also @racket[html-defaults],
@racket[latex-defaults], and @secref["config"].
For any output form, use the @DPFlag{extra} flag to add a needed file
to the build destination, such as an image file that is referenced in
the generated output but not included via @racket[image] (which copies
the file automatically).
@section[#:tag "xref-flags"]{Handling Cross-References}
Cross references within a document or documents rendered together are
always resolved. When cross references span documents that are
rendered separately, cross-reference information needs to be saved and
loaded explicitly. Cross-reference information is format-specific, but
HTML-format information is usable for Latex (or PDF) or text rendering.
A Racket installation includes HTML-format cross-reference information
for all installed documentation. Each document's information is in a
separate file, so that loading all relevant files would be tedious.
The @PFlag{m} or @DPFlag{main-xref-in} flag loads cross-reference
information for all installed documentation, so
@commandline{scribble +m mine.scrbl}
renders @filepath{mine.scrbl} to @filepath{mine.html} with
cross-reference links to the Racket installation's documentation.
(The @filepath{racket-index} package must be installed to use
@PFlag{m}/@DPFlag{main-xref-in}.)
The @DPFlag{xref-in} flag loads cross-reference information by calling
a specified module's function. The @racketmodname[setup/xref] module
provides @racket[load-collections-xref] to load cross-reference
information for all installed documentation, and @PFlag{m} or
@DPFlag{main-xref-in} is just a shorthand for @exec{++xref-in
setup/xref load-collections-xref}.
The @DFlag{redirect-main} flag for HTML output redirects links to the local
installation's documentation to a given URL, such as
@tt{http://docs.racket-lang.org/}. Beware that documentation links
sometimes change (although Scribble generates HTML paths and anchors
in a relatively stable way), so
@tt{http://download.racket-lang.org/docs/@italic{version}/html/} may be
more reliable when building with an installation for @italic{version}.
The @DFlag{redirect-main} flag is ignored for non-HTML output.
The @DFlag{redirect} flag is like @DFlag{redirect-main}, except
that it builds on the given URL to indicate a cross-reference tag that
is more stable than an HTML path and anchor (in case the documentation
for a function changes sections, for example). No server currently
exists to serve such tag requests, however.
For cross-references among documentation that is not part of the
Racket installation, use @DFlag{info-out} to save information from a
document build and use @DPFlag{info-in} to load previously saved
information. For example, if @filepath{c.scrbl} refers to information
in @filepath{a.scrbl} and @filepath{b.scrbl}, then
@commandline{scribble --info-out a.sxref a.scrbl}
@commandline{scribble --info-out b.sxref b.scrbl}
@commandline{scribble ++info-in a.sxref ++info-in b.sxref c.scrbl}
builds @filepath{c.html} with cross-reference links into
@filepath{a.html} and @filepath{b.html}.
@section{Selecting an Image Format}
Use the @DPFlag{convert} @nonterm{fmt} flag to select @nonterm{fmt} as
a preferred image format to use when rendering a document that
includes values that can be converted to different image formats. The
@nonterm{fmt} argument can be @exec{pdf}, @exec{ps}, @exec{png},
@exec{svg}, or @exec{gif}, but a renderer typically supports only a
subset of those formats.
Use @DPFlag{convert} @nonterm{fmt} multiple times to specify multiple
preferred formats, where a @nonterm{fmt} earlier in the command line
take precedence over @nonterm{fmt}s specified later.
For example, to generate Latex sources with images in Encapsulated
PostScript format (so that the result works with @exec{latex} instead
of @exec{pdflatex}), combine @DFlag{latex} with @exec{@DPFlag{convert}
ps}. To generate HTML pages with images converted to SVG format
instead of PNG format, combine @DFlag{html} with
@exec{@DPFlag{convert} svg}.
@history[#:changed "1.4" @elem{Added @DPFlag{convert} support.}]
@section{Passing Command-Line Arguments to Documents}
When @exec{scribble} loads and renders a document module, by default
it sets @racket[current-command-line-arguments] to an empty vector.
Use the @DPFlag{arg} flag (any number of times) to add a string to
@racket[current-command-line-arguments].
For example,
@commandline{scribble ++arg --mode ++arg fast turtle.scrbl}
causes @racket[(current-command-line-arguments)] to return
@racket['#("--mode" "fast")] while @filepath{turtle.scrbl} is loaded
and rendered, which could affect the content that
@filepath{turtle.scrbl} generates if it uses
@racket[current-command-line-arguments].
@history[#:changed "1.1" @elem{Added the empty-vector default and @DPFlag{arg} flag.}]

223
scribble-doc/scribblings/scribble/scheme.scrbl
View File

@ -1,223 +0,0 @@
#lang scribble/doc
@(require scribble/manual "utils.rkt" (for-label scribble/racket))
@title[#:tag "scheme"]{Racket}
@defmodule*[(scribble/racket scribble/scheme)]{The
@racket[scribble/racket] library (or @racketmodname[scribble/scheme]
for backward compatibility) provides utilities for typesetting Racket
code. The @racket[scribble/manual] forms provide a higher-level
interface.}
@defform*[[(define-code id typeset-expr)
(define-code id typeset-expr uncode-id)
(define-code id typeset-expr uncode-id d->s-expr)
(define-code id typeset-expr uncode-id d->s-expr stx-prop-expr)]]{
Binds @racket[id] to a form similar to @racket[racket] or
@racket[racketblock] for typesetting code. The form generated by
@racket[define-code] handles source-location information, escapes via
@racket[unquote] by default, preserves binding and property information,
and supports @tech{element transformers}.
The supplied @racket[typeset-expr] expression should produce a
procedure that performs the actual typesetting. This expression is
normally @racket[to-element] or @racket[to-paragraph]. The argument
supplied to @racket[typeset-expr] is normally a syntax object, but
more generally it is the result of applying @racket[d->s-expr].
The optional @racket[uncode-id] specifies the default escape from
literal code to be recognized by @racket[id], and the default for
@racket[uncode-id] is @racket[unsyntax]. A use of the @racket[id] form
can specify an alternate escape via @racket[#:escape], as in
@racket[racketblock] and @racket[racket].
The optional @racket[d->s-expr] should produce a procedure that
accepts three arguments suitable for @racket[datum->syntax]: a syntax
object or @racket[#f], an arbitrary value, and a vector for a source
location. The result should record as much or as little of the
argument information as needed by @racket[typeset-expr] to typeset the
code. Normally, @racket[d->s-expr] is @racket[datum->syntax].
The @racket[stx-prop-expr] should produce a procedure for recording a
@racket['paren-shape] property when the source expression uses with
@racket[id] has such a property. The default is
@racket[syntax-property].}
@defproc[(to-paragraph [v any/c]
[#:expr? expr? any/c #f]
[#:escapes? escapes? any/c #t]
[#:color? color? any/c #t]
[#:wrap-elem wrap-elem (element? . -> . element?) (lambda (e) e)])
block?]{
Typesets an S-expression that is represented by a syntax object, where
source-location information in the syntax object controls the
generated layout. When source-location information is not available,
default spacing is used (in the same single-line style as
@racket[to-element]).
Identifiers that have @racket[for-label] bindings are typeset and
hyperlinked based on definitions declared elsewhere (via
@racket[defproc], @racket[defform], etc.). Unless @racket[escapes?]
is @racket[#f], the identifiers
@racketidfont{code:line}, @racketidfont{code:comment},
@racketidfont{code:blank}, @racketidfont{code:hilite}, and
@racketidfont{code:quote} are handled as in @racket[racketblock], as
are identifiers that start with @litchar{_}.
In addition, the given @racket[v] can contain @racket[var-id],
@racket[shaped-parens], @racket[just-context], or
@racket[literal-syntax] structures to be typeset specially (see each
structure type for details), or it can contain @racket[element]
structures that are used directly in the output.
If @racket[expr?] is true, then @racket[v] is rendered in expression
style, much like @racket[print] with the @racket[print-as-expression]
parameter set to @racket[#t]. In that case, @racket[for-label]
bindings on identifiers are ignored, since the identifiers are all
quoted in the output. Typically, @racket[expr?] is set to true for
printing result values.
If @racket[color?] is @racket[#f], then the output is typeset without
coloring.
The @racket[wrap-elem] procedure is applied to each element
constructed for the resulting block. When combined with @racket[#f]
for @racket[color?], for example, the @racket[wrap-elem] procedure can
be used to give a style to an element.}
@defproc[((to-paragraph/prefix [prefix1 any/c] [prefix any/c] [suffix any/c])
[v any/c] [#:expr? expr? any/c #f] [#:escapes? escapes? any/c #t]
[#:color? color? any/c #f]
[#:wrap-elem wrap-elem (element? . -> . element?) (lambda (e) e)])
block?]{
Like @racket[to-paragraph], but @racket[prefix1] is prefixed onto the
first line, @racket[prefix] is prefix to any subsequent line, and
@racket[suffix] is added to the end. The @racket[prefix1],
@racket[prefix], and @racket[suffix] arguments are used as
@tech{content}, except that if @racket[suffix] is a list of elements,
it is added to the end on its own line.}
@defproc[(to-element [v any/c]
[#:expr? expr? any/c #f]
[#:escapes? escapes? any/c #t]
[#:defn? defn? any/c #f]) element?]{
Like @racket[to-paragraph], except that source-location information is
mostly ignored, since the result is meant to be inlined into a
paragraph. If @racket[defn?] is true, then an identifier is styled as
a definition site.}
@defproc[(to-element/no-color [v any/c]
[#:expr? expr? any/c #f]
[#:escapes? escapes? any/c #t])
element?]{
Like @racket[to-element], but @racket[for-syntax] bindings are
ignored, and the generated text is uncolored. This variant is
typically used to typeset results.}
@defstruct[var-id ([sym (or/c symbol? identifier?)])]{
When @racket[to-paragraph] and variants encounter a @racket[var-id]
structure, it is typeset as @racket[sym] in the variable font, like
@racket[racketvarfont]---unless the @racket[var-id] appears under
quote or quasiquote, in which case @racket[sym] is typeset as a symbol.}
@defstruct[shaped-parens ([val any/c]
[shape char?])]{
When @racket[to-paragraph] and variants encounter a
@racket[shaped-parens] structure, it is typeset like a syntax object
that has a @racket['paren-shape] property with value @racket[shape].}
@defstruct[long-boolean ([val boolean?])]{
When @racket[to-paragraph] and variants encounter a
@racket[long-boolean] structure, it is typeset as @racket[#true] or @racket[#false],
as opposed to @racket[#t] or @racket[#f].}
@defstruct[just-context ([val any/c]
[context syntax?])]{
When @racket[to-paragraph] and variants encounter a
@racket[just-context] structure, it is typeset using the
source-location information of @racket[val] just the lexical context
of @racket[ctx].}
@defstruct[literal-syntax ([stx any/c])]{
When @racket[to-paragraph] and variants encounter a
@racket[literal-syntax] structure, it is typeset as the string form of
@racket[stx]. This can be used to typeset a syntax-object value in the
way that the default printer would represent the value.}
@defproc[(element-id-transformer? [v any/c]) boolean?]{
Provided @racket[for-syntax]; returns @racket[#t] if @racket[v] is an
@tech{element transformer} created by
@racket[make-element-id-transformer], @racket[#f] otherwise.}
@defproc[(make-element-id-transformer [proc (syntax? . -> . syntax?)])
element-id-transformer?]{
Provided @racket[for-syntax]; creates an @deftech{element
transformer}. When an identifier has a transformer binding to an
@tech{element transformer}, then forms generated by
@racket[define-code] (including @racket[racket] and
@racket[racketblock]) typeset the identifier by applying the
@racket[proc] to the identifier. The result must be an expression
whose value, typically an @racket[element], is passed on to functions
like @racket[to-paragraph] .}
@defproc[(variable-id? [v any/c]) boolean?]{
Provided @racket[for-syntax]; returns @racket[#t] if @racket[v] is an
@tech{element transformer} created by @racket[make-variable-id],
@racket[#f] otherwise.}
@defproc[(make-variable-id [sym (or/c symbol? identifier?)])
variable-id?]{
Provided @racket[for-syntax]; like @racket[make-element-id-transformer] for
a transformer that produces @racket[sym] typeset as a variable (like
@racket[racketvarfont])---unless it appears under quote or quasiquote,
in which case @racket[sym] is typeset as a symbol.}
@deftogether[(
@defthing[output-color style?]
@defthing[input-color style?]
@defthing[input-background-color style?]
@defthing[no-color style?]
@defthing[reader-color style?]
@defthing[result-color style?]
@defthing[keyword-color style?]
@defthing[comment-color style?]
@defthing[paren-color style?]
@defthing[meta-color style?]
@defthing[value-color style?]
@defthing[symbol-color style?]
@defthing[variable-color style?]
@defthing[opt-color style?]
@defthing[error-color style?]
@defthing[syntax-link-color style?]
@defthing[value-link-color style?]
@defthing[module-color style?]
@defthing[module-link-color style?]
@defthing[block-color style?]
@defthing[highlighted-color style?]
)]{
Styles that are used for coloring Racket programs, results, and I/O.}

26
scribble-doc/scribblings/scribble/scribble-pp.scrbl
View File

@ -1,26 +0,0 @@
#lang scribble/manual
@(require "utils.rkt")
@title{Scribble as Preprocessor}
@author["Matthew Flatt" "Eli Barzilay"]
@section-index["Preprocessor"]
The @racketmodname[scribble/text] and @racketmodname[scribble/html]
languages act as ``preprocessor'' languages for generating text or
HTML. These preprocessor languages use the same @"@" syntax as the
main Scribble tool (see @other-doc['(lib
"scribblings/scribble/scribble.scrbl")]), but instead of working in
terms of a document abstraction that can be rendered to text and HTML
(and other formats), the preprocessor languages work in a way that is
more specific to the target formats.
@table-of-contents[]
@; ------------------------------------------------------------------------
@include-section["text.scrbl"]
@include-section["html.scrbl"]
@index-section[]

32
scribble-doc/scribblings/scribble/scribble.scrbl
View File

@ -1,32 +0,0 @@
#lang scribble/manual
@(require "utils.rkt")
@title{Scribble: The Racket Documentation Tool}
@author["Matthew Flatt" "Eli Barzilay"]
Scribble is a collection of tools for creating prose
documents---papers, books, library documentation, etc.---in HTML or
PDF (via Latex) form. More generally, Scribble helps you write
programs that are rich in textual content, whether the content is
prose to be typeset or any other form of text to be generated
programmatically.
This document is itself written using Scribble. You can see its source
at
@(let ([url "https://github.com/racket/scribble/tree/master/scribble-doc/scribblings/scribble"])
(link url url)),
starting with the @filepath{scribble.scrbl} file.
@table-of-contents[]
@; ------------------------------------------------------------------------
@include-section["how-to-paper.scrbl"]
@include-section["reader.scrbl"]
@include-section["generic.scrbl"]
@include-section["plt.scrbl"]
@include-section["lp.scrbl"]
@include-section["internals.scrbl"]
@include-section["running.scrbl"]
@index-section[]

1
scribble-doc/scribblings/scribble/shaded.css
View File

@ -1 +0,0 @@

2
scribble-doc/scribblings/scribble/shaded.tex
View File

@ -1,2 +0,0 @@
\newcommand{\Short}[1]{\begin{minipage}[c]{6ex}#1\end{minipage}}

146
scribble-doc/scribblings/scribble/sigplan.scrbl
View File

@ -1,146 +0,0 @@
#lang scribble/manual
@(require "utils.rkt" (for-label scribble/sigplan))
@title{SIGPLAN Paper Format}
@defmodulelang[scribble/sigplan]{The @racketmodname[scribble/sigplan]
language is like @racketmodname[scribble/base], but configured with
Latex style defaults to use the @filepath{sigplanconf.cls} class
file that is included with Scribble.}
@defidform[preprint]{
Enables the @tt{preprint} option. Use @racket[preprint] only on the
same line as @hash-lang[], with only whitespace (or other options) between
@racketmodname[scribble/sigplan] and @racket[preprint]:
@verbatim[#:indent 2]|{
#lang scribble/sigplan @preprint
}|}
@defidform[10pt]{
Enables the @tt{10pt} option. Use @racket[10pt] only on the
same line as @hash-lang[], with only whitespace (or other options) between
@racketmodname[scribble/sigplan] and @racket[10pt]:
@verbatim[#:indent 2]|{
#lang scribble/sigplan @10pt
}|
@defidform[nocopyright]{
Enables the @tt{nocopyright} option. Use @racket[nocopyright] only on the
same line as @hash-lang[], with only whitespace (or other options) between
@racketmodname[scribble/sigplan] and @racket[nocopyright]:
@verbatim[#:indent 2]|{
#lang scribble/sigplan @nocopyright
}|}
@defidform[onecolumn]{
Enables the @tt{onecolumn} option. Use only on the
same line as @hash-lang[], with only whitespace (or other options) between
@racketmodname[scribble/sigplan] and @racket[onecolumn]:
@codeblock|{
#lang scribble/sigplan @onecolumn
}|}
@defidform[notimes]{
Disables the use of @tt{\usepackage@"{"times@"}"} in the generated LaTeX output.
Use only on the same line as @hash-lang[],
with only whitespace (or other options) between
@racketmodname[scribble/sigplan] and @racket[notimes]:
@codeblock|{
#lang scribble/sigplan @notimes
}|}
@defidform[noqcourier]{
Disables the use of @tt{\usepackage@"{"qcourier@"}"} in the generated LaTeX output.
Use only on the same line as @hash-lang[],
with only whitespace (or other options) between
@racketmodname[scribble/sigplan] and @racket[noqcourier]:
@codeblock|{
#lang scribble/sigplan @noqcourier
}|}
The @racket[10pt], @racket[preprint], @racket[nocopyright],
@racket[onecolumn], @racket[notimes], and @racket[noqcourier]
options can be used together and may appear in any order.
}
@defproc[(abstract [pre-content pre-content?] ...) block?]{
Generates a @tech{nested flow} for a paper abstract.}
@defform[(include-abstract module-path)]{
Similar to @racket[include-section], but incorporates the document in the
specified module as an abstract. The document must have no title or
sub-parts.}
@defproc[(subtitle [pre-content pre-content?] ...) element?]{
Use as the last argument to @racket[title] to specify a subtitle.}
@defproc[(authorinfo [name pre-content?]
[affiliation pre-content?]
[email pre-content?])
block?]{
A replacement for @racket[author] that associates an affiliation and
e-mail address with the author name.}
@deftogether[(
@defproc[(conferenceinfo [conference pre-content?] [location pre-content?]) block?]
@defproc[(copyrightyear [content pre-content?] ...) block?]
@defproc[(copyrightdata [content pre-content?] ...) block?]
@defproc[(doi [content pre-content?] ...) block?]
@defproc[(exclusive-license) block?]
)]{
Declares information that is collected into the copyright region of the paper.}
@defproc[(to-appear [content pre-content?] ...) block?]{
Declares alternate content for the copyright region of the paper.
@history[#:added "1.13"]}
@deftogether[(
@defproc[(category [CR-number pre-content?]
[subcategory pre-content?]
[third-level pre-content?]
[fourth-level (or/c #f pre-content?) #f]) content?]
@defproc[(terms [content pre-content?] ...) content?]
@defproc[(keywords [content pre-content?] ...) content?]
)]{
Typesets category, term, and keyword information for the paper, which
is normally placed immediately after an @racket[abstract] form.
See also @url["http://www.acm.org/about/class/how-to-use"].
For @racket[category], the @racket[subcategory] argument should be in
titlecase (i.e., capitalize the first letter of each word) and a
phrase at the level of ``Programming Languages'' or ``Software
Engineering'' (as opposed to a category like ``Software'' or a
third-level name like ``Concurrent Programming'' or ``Processors''). A
@racket[third-level] phrase should be in titlecase. A
@racket[fourth-level] phrase, if any, should not be capitalized.
For @racket[terms], each general term should be in titlecase. Terms
are usually drawn from a fixed list, and they are usually optional.
For @racket[keywords], capitalize only the first letter of the first
word, separate phrases by commas, and do not include ``and'' before
the last one. Keywords should be noun phrases, not adjectives.}

258
scribble-doc/scribblings/scribble/srcdoc.scrbl
View File

@ -1,258 +0,0 @@
#lang scribble/doc
@(require scribble/manual "utils.rkt"
(for-label scribble/srcdoc scribble/extract racket/contract))
@title[#:tag "srcdoc"]{In-Source Documentation}
The @racketmodname[scribble/srcdoc] and
@racketmodname[scribble/extract] libraries support writing
documentation within the documented code along with an export
contract, similar to using @as-index{JavaDoc}. With this approach, a
single contract specification is used both for the run-time contract
and the documentation of an exported binding.
The @racketmodname[scribble/srcdoc] library provides forms for
exporting a binding with associated documentation. The
@racket[scribble/extract] library is used to pull
@racket[scribble/srcdoc]-based documentation into a Scribble document
(perhaps for multiple libraries).
Although documentation is written with a library's implementation when
using @racketmodname[scribble/srcdoc], the documentation creates no
run-time overhead for the library. Similarly, typesetting the
documentation does not require running the library. The two phases
(run time versus documentation time) are kept separate in much the
same way that the module system keeps expansion-time code separate
from run-time code, and documentation information is recorded in a
submodule to be separately loadable from the enclosing module.
For an example use, see the @filepath{file} collection's
@filepath{gif.rkt} source file and the corresponding extraction in
@filepath{scribblings/gif.scrbl}. As that example illustrates,
starting the module declaration with
@racketblock[
@#,hash-lang[] @#,racketmodname[at-exp]
]
enables the @"@"-reader, which is handy for writing documentation
expressions.
@; ----------------------------------------
@section{Source Annotations for Documentation}
@defmodule[scribble/srcdoc]
Documentation information generated by @racketmodname[scribble/srcdoc]
forms are accumulated into a @racketidfont{srcdoc} submodule. The
generated submodule is accessed by the bindings of
@racketmodname[scribble/extract].
@defform[(for-doc require-spec ...)]{
A @racket[require] sub-form for bindings that are needed at
documentation time (and documentation-expansion time, etc.) instead of
run time (and expansion time, etc.). A @racket[for-doc] import has
no effect on a normal use of the library; it affects only
documentation extraction.
Typically, a library that uses @racketmodname[scribble/srcdoc]
includes at least @racket[(require (for-doc scribble/base scribble/manual))]
to get core Racket forms and basic Scribble functions to use in
documentation expressions.}
@defform*/subs[#:literals (-> ->* case->)
[(proc-doc/names id contract arg-specs (desc-expr ...))]
([arg-specs ((arg-id ...) ((arg-id default-expr) ...))
(arg-id ...)]
[contract (-> arg ... result)
(->* (mandatory ...) (optional ...) result)
(case-> (-> arg ... result) ...)]
[mandatory contract-expr
(code:line keyword contract-expr)]
[optional contract-expr
(code:line keyword contract-expr)])]{
A @racket[provide] sub-form that exports @racket[id] with the
contract described by @racket[contract]
just like using @racket[contract-out].
The @racket[arg-spec] specifies the names of arguments and the
default values, which are not
normally written as part of a contract. They are combined with the
contract expression to generate the description of the binding in the
documentation via @racket[defproc]. The @racket[(arg-id default-expr)]
pairs specify the names and default values of the optional arguments.
If the contract supports optional arguments, then the first
@racket[arg-spec]s form must be used, otherwise the second must be used.
The @racket[desc-expr] is a sequence of documentation-time expressions that
produces prose to describe the exported binding---that is, the last
part of the generated @racket[defproc], so the description can refer
to the @racket[arg-id]s using @racket[racket].
The normal @racket[require]s of the enclosing library are effectively
converted into @racket[for-label] @racket[require]s when generating
documentation, so that identifiers in the @racket[contract]s are
linked to their corresponding documentation. Similarly, any binding
that is available in the run-time phase of the enclosing library
can be referenced in documentation prose using the @racket[racket]
form.}
@defform/subs[#:literals (-> ->i ->d values)
(proc-doc id contract maybe-defs (desc-expr ...))
([contract (-> result)
(->i (arg ...) (opt ...) maybe-pre [id res])
(->i (arg ...) (opt ...) maybe-pre (values [id res] ...))
(->i (arg ...) (opt ...) #:rest rest [id result-expr])
(->d (arg ...) () maybe-pre (values [id result] ...))
(->d (arg ...) () maybe-pre [id result])
(->d (arg ...) () #:rest id rest [id result])]
[maybe-pre (code:line)
(code:line #:pre (pre-id ...) condition)]
[maybe-defs (code:line)
(default-expr default-expr ...)])]{
Like @racket[proc-doc/names], but supporting contract forms that embed
argument identifiers. Only a subset of @racket[->i] and @racket[->d] forms are
currently supported.
If the sequence of optional arguments, @racket[(opt ...)] is empty then
the @racket[maybe-arg-desc] must be not be present. If it is non-empty,
then it must have as many default expressions are there are optional
arguments.
}
@defform[(thing-doc id contract-expr (desc-expr ...))]{
Like @racket[proc-doc], but for an export of an arbitrary value.}
@defform[#:literals (parameter/c)
(parameter-doc id (parameter/c contract-expr) arg-id (desc-expr ...))]{
Like @racket[proc-doc], but for exporting a parameter.}
@defform[(struct*-doc struct-name
([field-name contract-expr-datum] ...)
maybe-omit-constructor
maybe-mutable maybe-non-opaque maybe-constructor
(desc-expr ...))
#:grammar ([maybe-omit-constructor (code:line) #:omit-constructor])]{
Like @racket[proc-doc], but for struct declarations that use @racket[struct].
The @racket[maybe-mutable], @racket[maybe-non-opaque], and @racket[maybe-constructor]
options are as in @racket[defstruct].
}
@defform[(struct-doc struct-name
([field-name contract-expr-datum] ...)
maybe-omit-constructor
maybe-mutable maybe-non-opaque maybe-constructor
(desc-expr ...))]{
Like @racket[struct*-doc], but for struct declarations that use @racket[define-struct].
}
@defform/subs[(form-doc options form-datum
maybe-grammar maybe-contracts
(desc-expr ...))
([options (code:line maybe-kind maybe-link maybe-id maybe-literals)]
[maybe-kind code:blank
(code:line #:kind kind-string-expr)]
[maybe-link code:blank
(code:line #:link-target? link-target?-expr)]
[maybe-id code:blank
(code:line #:id id)
(code:line #:id [id id-expr])]
[maybe-literals code:blank
(code:line #:literals (literal-id ...))]
[maybe-grammar code:blank
(code:line #:grammar ([nonterm-id clause-datum ...+] ...))]
[maybe-contracts code:blank
(code:line #:contracts ([subform-datum contract-expr-datum]
...))])]{
Like @racket[proc-doc], but for an export of a syntactic form. If
@racket[#:id] is provided, then @racket[id] is the exported identifier,
otherwise the exported identifier is extracted from @racket[form-datum].
See @racket[defform] for information on @racket[options],
@racket[form-datum], @racket[maybe-grammar], and
@racket[maybe-contracts].
@history[#:added "1.6"]}
@defform[(begin-for-doc form ...)]{
Like to @racket[begin-for-syntax], but for documentation time instead
of expansion time. The @racket[form]s can refer to binding
@racket[require]d with @racket[for-doc].
For example, a definition in @racket[begin-for-doc]
can be referenced by a @racket[_desc-expr] in
@racket[proc-doc/names].}
@defform[(generate-delayed-documents)]{
Causes documentation information to be recorded as a macro that is
expanded (along with any @racket[for-doc] imports) in the
module that uses @racket[include-extracted] or @racket[provide-extracted],
instead of within (a submodule of) the module that declares the information.
Delaying document generation in this way allows @racket[(for-doc
(for-label ....))] imports that would otherwise create cyclic module
dependencies.
To avoid problems with accumulated @racket[for-doc] imports across
modules, @racket[generate-delayed-documents] declaration should appear
before any @racket[for-doc] import.}
@defform[(require/doc require-spec ...)]{
A legacy shorthand for @racket[(require (for-doc require-spec ...))].}
@defform[(provide/doc spec ...)]{
A legacy alternative to @racket[(provide spec ...)]}
@; ----------------------------------------
@section{Extracting Documentation from Source}
@defmodule[scribble/extract]
@defform[(include-extracted module-path)]{
Expands to a sequence of documentation forms extracted from
@racket[module-path], which is expected to be a module that uses
@racketmodname[scribble/srcdoc] (so that the module has a
@racketidfont{srcdoc} submodule).}
@defform[(provide-extracted module-path)]{
Similar to @racket[include-extracted], but the documentation is
packaged and exported as @racket[exported], instead of left
inline.
Use this form in combination with
@racket[include-previously-extracted] when documentation from a single
source is to be split and typeset among multiple documentation
locations. The @racket[provide-extracted] form extracts the
documentation once, and then @racket[include-previously-extracted]
form extracts documentation for specific bindings as needed.}
@defform[(include-previously-extracted module-path regexp)]{
Similar to @racket[include-extracted], but instead of referring to the
source that contains its own documentation, @racket[module-path]
refers to a module that uses @racket[provide-extracted]. The
@racket[include-previously-extracted] form expands to documentation
forms for all identifiers whose string forms match @racket[regexp].}

393
scribble-doc/scribblings/scribble/struct-hierarchy.rkt
View File

@ -1,393 +0,0 @@
#lang racket/base
(require "class-diagrams.rkt"
(only-in pict pin-arrow-line)
texpict/mrpict
(except-in texpict/utils pin-arrow-line)
racket/system
racket/class
racket/draw)
(define (mk-ps-diagram)
;; thicken up the lines for postscript
(linewidth .8 (mk-diagram)))
(provide mk-diagram)
(define (mk-diagram)
(define part-name (class-name "part" #:spacing-word "subparts"))
(define part-blocks-field (field-spec #f "blocks"))
(define part-subparts-field (field-spec #f "subparts"))
(define part-title-field (field-spec #f "title"))
(define part-box (class-box part-name (list part-title-field part-blocks-field part-subparts-field) #f))
(define block-name (class-name "block"))
(define block-box (class-box block-name #f #f))
(define para-name (class-name "paragraph"))
(define para-style (field-spec #f "style"))
(define para-content (field-spec #f "content"))
(define para-box (class-box para-name (list para-style para-content) #f))
(define compound-para-name (class-name "compound-\nparagraph"))
(define compound-para-style (field-spec #f "style"))
(define compound-para-blocks (field-spec #f "blocks"))
(define compound-para-box (class-box compound-para-name (list compound-para-style compound-para-blocks) #f))
(define table-name (class-name "table"))
(define table-style (field-spec #f "style"))
(define table-cells (field-spec #f "cells")) ;; blockss
(define table-box (class-box table-name (list table-style table-cells) #f))
(define itemization-name (class-name "itemization"))
(define itemization-style (field-spec #f "style"))
(define itemization-items (field-spec #f "items")) ;; blockss
(define itemization-box (class-box itemization-name (list itemization-style itemization-items) #f))
(define nested-flow-name (class-name "nested-\nflow"))
(define nested-flow-style (field-spec #f "style"))
(define nested-flow-blocks (field-spec #f "blocks"))
(define nested-flow-box (class-box nested-flow-name (list nested-flow-style nested-flow-blocks) #f))
(define delayed-block-name (class-name "delayed-block"))
(define delayed-block-block (field-spec #f "block"))
(define delayed-block-box (class-box delayed-block-name (list delayed-block-block) #f))
(define traverse-block-name (class-name "traverse-\nblock"))
(define traverse-block-block (field-spec #f "block"))
(define traverse-block-box (class-box traverse-block-name (list traverse-block-block) #f))
(define content-name (class-name "content"))
(define content-box (class-box content-name #f #f))
(define string-name (class-name "string"))
(define string-box (class-box string-name #f #f))
(define symbol-name (class-name "symbol"))
(define symbol-box (class-box symbol-name #f #f))
(define pict-name (class-name "pict"))
(define pict-box (class-box pict-name #f #f))
(define convertible-name (class-name "convertible"))
(define convertible-box (class-box convertible-name #f #f))
(define list-name (class-name "list"))
(define list-box (class-box list-name #f #f))
(define delayed-element-name (class-name "delayed-\nelement"))
(define delayed-element-content (field-spec #f "content"))
(define delayed-element-box (class-box delayed-element-name (list delayed-element-content) #f))
(define render-element-name (class-name "render-\nelement"))
(define render-element-content (field-spec #f "content"))
(define render-element-box (class-box render-element-name (list render-element-content) #f))
(define traverse-element-name (class-name "traverse-\nelement"))
(define traverse-element-content (field-spec #f "content"))
(define traverse-element-box (class-box traverse-element-name (list traverse-element-content) #f))
(define part-relative-element-name (class-name "part-\nrelative-\nelement"))
(define part-relative-element-resolve (field-spec #f "resolve"))
(define part-relative-element-box (class-box part-relative-element-name (list part-relative-element-resolve) #f))
(define element-name (class-name "element"))
(define element-style (field-spec #f "style"))
(define element-content (field-spec #f "content"))
(define element-box (class-box element-name (list element-style element-content) #f))
(define link-element-name (class-name "link-\nelement"))
(define link-tag (field-spec #f "tag"))
(define link-element-box (class-box link-element-name
(list link-tag)
#f))
(define collect-element-name (class-name "collect-\nelement"))
(define collect-element-collect (field-spec #f "collect"))
(define collect-element-box (class-box collect-element-name (list collect-element-collect) #f))
(define index-element-name (class-name "index-\nelement" #:spacing-word "keywords"))
(define index-element-tag (field-spec #f "tag"))
(define index-element-keywords (field-spec #f "keywords"))
(define index-element-box (class-box index-element-name
(list index-element-tag index-element-keywords)
#f))
(define image-element-name (class-name "image-\nelement" #:spacing-word "suffixes"))
(define image-element-path (field-spec #f "path"))
(define image-element-suffixes (field-spec #f "suffixes"))
(define image-element-scale (field-spec #f "scale"))
(define image-element-box (class-box image-element-name
(list image-element-path
image-element-suffixes
image-element-scale)
#f))
(define multiarg-element-name (class-name "multiarg-\nelement"))
(define multiarg-element-tag (field-spec #f "tag"))
(define multiarg-element-box (class-box multiarg-element-name (list multiarg-element-tag) #f))
(define target-element-name (class-name "target-\nelement"))
(define target-tag (field-spec #f "tag"))
(define target-element-box (class-box target-element-name
(list target-tag)
#f))
(define redirect-target-element-name (class-name "redirect-target-\nelement"))
(define redirect-target-alt-path (field-spec #f "alt-path"))
(define redirect-target-alt-anchor (field-spec #f "alt-anchor"))
(define redirect-target-element-box (class-box redirect-target-element-name
(list redirect-target-alt-path redirect-target-alt-anchor)
#f))
(define toc-target-element-name (class-name "toc-target-\nelement"))
(define toc-target-element-box (class-box toc-target-element-name (list) #f))
(define page-target-element-name (class-name "page-target-\nelement"))
(define page-target-element-box (class-box page-target-element-name (list) #f))
(define block-hierarchy
(hierarchy
(vc-append block-box
(blank 0 50)
(ht-append 20
(ht-append 30
compound-para-box
para-box)
(vc-append (blank 0 30) itemization-box)
table-box)
(blank 0 25)
(ht-append nested-flow-box
(blank 120 0)
(vc-append (blank 0 30) delayed-block-box)
(blank 80 0)
traverse-block-box))
(list block-box)
(list compound-para-box
para-box
nested-flow-box
itemization-box
table-box
delayed-block-box
traverse-block-box)))
(define target-element-hierarchy
(hierarchy
(vc-append target-element-box
(blank 0 50)
(ht-append 20
toc-target-element-box
page-target-element-box
redirect-target-element-box))
(list target-element-box)
(list toc-target-element-box
page-target-element-box
redirect-target-element-box)))
(define element-hierarchy
(hierarchy
(vc-append element-box
(blank 0 50)
(inset (ht-append 20
collect-element-box
multiarg-element-box
(refocus target-element-hierarchy target-element-box)
link-element-box
image-element-box
index-element-box)
0 0 -400 0))
(list element-box)
(list collect-element-box
index-element-box
image-element-box
target-element-box
multiarg-element-box
link-element-box
)))
(define render-element-parent-link (blank))
(define delayed-element-parent-link (blank))
(define part-relative-element-parent-link (blank))
(define traverse-element-parent-link (blank))
(define element-parent-link (blank))
(define (drop-and-link box parent-link i)
(vc-append
(blank 0 (+ 40 (* i 20)))
(refocus (ct-superimpose box parent-link)
parent-link)))
(define content-hierarchy
(hierarchy
(vc-append content-box
(blank 0 50)
(ht-append 15
(drop-and-link (refocus element-hierarchy element-box)
element-parent-link
4)
convertible-box
(drop-and-link render-element-box
render-element-parent-link
4)
pict-box
(drop-and-link delayed-element-box
delayed-element-parent-link
3)
symbol-box
(drop-and-link part-relative-element-box
part-relative-element-parent-link
1)
string-box
(drop-and-link traverse-element-box
traverse-element-parent-link
0)
list-box))
(list content-box)
(list element-box
string-box
symbol-box
convertible-box
pict-box
traverse-element-parent-link
part-relative-element-parent-link
delayed-element-parent-link
render-element-parent-link
list-box)))
(define raw
(vc-append part-box
(blank 0 20)
(vc-append block-hierarchy
(blank 0 20)
content-hierarchy)))
(define w/connections
(double
right-right-reference
(double
left-left-reference
(triple
right-right-reference
(triple
right-right-reference
(double
left-left-reference
(double
left-left-reference
(double
right-right-reference
(double
left-left-reference
(double
left-left-reference
(left-left-reference
raw
element-box element-content content-box content-name 1 #:dot-delta -1)
part-box part-title-field content-box content-name 21)
part-box part-blocks-field block-box block-name)
part-box part-subparts-field part-box part-name 2)
para-box para-content content-box content-name 2)
compound-para-box compound-para-blocks block-box block-name 3)
table-box table-cells block-box block-name 2)
itemization-box itemization-items block-box block-name 10)
nested-flow-box nested-flow-blocks block-box block-name 1)
list-box list-box content-box content-name))
(define w/delayed-connections
(dotted-right-right-reference
(dotted-right-right-reference
(dotted-right-right-reference
(dotted-right-right-reference
(dotted-right-right-reference
(dotted-right-right-reference
w/connections
render-element-box render-element-content content-box content-name 30)
traverse-block-box traverse-block-block block-box block-name 1)
delayed-block-box delayed-block-block block-box block-name 17)
traverse-element-box traverse-element-content content-box content-name 3)
delayed-element-box delayed-element-content content-box content-name 22)
part-relative-element-box part-relative-element-resolve content-box content-name 12))
;; one extra pixel on the right so we get the
;; line drawn to the outermost turning point
(inset (panorama w/delayed-connections) 0 0 1 0))
(define (double f p0 a b c d [count 1])
(let ([arrows1 (launder (f (ghost p0) a b c d count #:dot-delta 1))]
[arrows2 (launder (f (ghost p0) a b c d count #:dot-delta -1))])
(cc-superimpose p0
arrows1
arrows2)))
(define (triple f p0 a b c d [count 1])
(let ([arrows (launder (f (ghost p0) a b c d count))]
[up-arrows (launder (f (ghost p0) a b c d count #:dot-delta 2))]
[down-arrows (launder (f (ghost p0) a b c d count #:dot-delta -2))])
(cc-superimpose p0
arrows
up-arrows
down-arrows)))
(define (connect-circly-dots show-arrowhead? main dot1 . dots)
(let loop ([prev-dot dot1]
[dots dots]
[pict main])
(cond
[(null? dots) pict]
[else
(loop (car dots)
(cdr dots)
(connect-two-circly-dots pict prev-dot (car dots) (null? (cdr dots))))])))
;; this is a hack -- it will only work with right-right-reference
(define (connect-two-circly-dots pict dot1 dot2 arrowhead?)
(let ([base
(let*-values ([(sx sy) (cc-find pict dot1)]
[(raw-ex ey) (cc-find pict dot2)]
[(ex) (if arrowhead?
(+ raw-ex 2)
raw-ex)])
(cc-superimpose
(dc
(λ (dc dx dy)
(let ([pen (send dc get-pen)])
(send dc set-pen
type-link-color ;(send pen get-color)
(if (is-a? dc post-script-dc%)
4
2)
'dot)
(send dc draw-line
(+ dx sx) (+ dy sy)
(+ dx ex) (+ dy ey))
(send dc set-pen pen)))
(pict-width pict)
(pict-height pict))
pict))])
(if arrowhead?
(pin-arrow-line field-arrowhead-size
base
dot1 (λ (ignored1 ignored2)
(let-values ([(x y) (cc-find pict dot2)])
(values (+ x 2) y)))
dot2 cc-find
#:color type-link-color)
base)))
(define (dotted-right-right-reference p0 a b c d [count 1])
(right-right-reference p0 a b c d count #:connect-dots connect-circly-dots))
(module+ slideshow
(require slideshow)
(define p (inset (mk-diagram) 0 0 0 1))
(define c (blank client-w client-h))
(slide (lt-superimpose (t "top") (clip (refocus (ct-superimpose p c) c))))
(slide (lt-superimpose (t "bottom") (clip (refocus (cb-superimpose p c) c))))
(slide (lt-superimpose (t "all")
(ct-superimpose
c
(scale p
(min (/ client-w (pict-width p))
(/ client-h (pict-height p))))))))

280
scribble-doc/scribblings/scribble/struct.scrbl
View File

@ -1,280 +0,0 @@
#lang scribble/manual
@(require (except-in "utils.rkt"
make-part make-paragraph make-table make-itemization make-compound-paragraph
make-element make-toc-element make-target-element make-toc-target-element make-toc-target2-element
make-page-target-element make-redirect-target-element make-link-element
make-index-element
make-target-url target-url struct:target-url target-url? target-url-addr
toc-element-toc-content toc-target2-element-toc-content part-title-content paragraph-content
element? element-content element-style)
(for-label scribble/manual-struct
scribble/struct
setup/main-collects))
@(define (compat) @italic{For backward compatibility.})
@(define-syntax-rule (compat/comp id)
@elem{@compat[] Compared to the normal constructor for @racket[id]})
@title[#:tag "struct"]{Compatibility Structures And Processing}
@defmodule[scribble/struct]{
The @racket[scribble/struct] compatibility library mostly re-exports
@racket[scribble/core], but using some different names (e.g.,
@racket[blockquote] instead of @racket[nested-flow]).}
The following structure types and functions are re-exported directly:
@racketblock[collect-info resolve-info tag? block?
delayed-block collected-info delayed-element ; delayed-element-content delayed-block-blocks current-serialize-resolve-info
part-relative-element collect-info-parents ; part-relative-element-content delayed-index-desc
collect-element render-element generated-tag ; generate-tag current-tag-prefixes add-current-tag-prefix
tag-key content->string element->string ; strip-aux
block-width element-width
info-key? part-collected-info collect-put!
resolve-get resolve-get/tentative resolve-get/ext?
resolve-search resolve-get-keys]
The following structure types are re-exported, but the constructors and some selectors
are replaced as documented further below:
@racketblock[part paragraph table itemization compound-paragraph
element toc-element target-element toc-target-element toc-target2-element
page-target-element redirect-target-element link-element
index-element]
Several additional compatibility functions and structure types are
also exported.
@defproc[(make-part [tag-prefix (or/c false/c string?)]
[tags (listof tag?)]
[title-content (or/c false/c list?)]
[style any/c]
[to-collect list?]
[blocks (listof block?)]
[parts (listof part?)])
part?]{
@compat/comp[part], parses @racket[style] to convert old formats to
the current one. Also, if @racket[title-content] is a list with a
single item, the item by itself is stored in the resulting
@racket[part].}
@defproc[(part-flow [p part?]) (listof block?)]{
@compat[] An alias for @racket[part-blocks].}
@defproc[(part-title-content [p part?]) list?]{
@compat[] Like the normal selector, but if the result would not be a list, it is
coerced to one.}
@deftogether[(
@defproc[(make-versioned-part [tag-prefix (or/c false/c string?)]
[tags (listof tag?)]
[title-content (or/c false/c list?)]
[style any/c]
[to-collect list?]
[blocks (listof block?)]
[parts (listof part?)]
[version string?])
part?]
@defproc[(versioned-part? [v any/c]) boolean?]
)]{
@compat[] Like @racket[make-part], but adds a the
@racket[document-version] @tech{style property} using the given
@racket[version]. The @racket[versioned-part?] predicate recognizes a
@racket[part] with a @racket[document-version] property.}
@deftogether[(
@defproc[(make-unnumbered-part [tag-prefix (or/c false/c string?)]
[tags (listof tag?)]
[title-content (or/c false/c list?)]
[style any/c]
[to-collect list?]
[blocks (listof block?)]
[parts (listof part?)])
part?]
@defproc[(unnumbered-part? [v any/c]) boolean?]
)]{
@compat[] Like @racket[make-part], but adds the @racket['unnumbered]
@tech{style property}. The @racket[unnumbered-part?] predicate
recognizes a @racket[part] with the @racket['unnumbered] property.}
@defproc[(make-paragraph [content list?]) paragraph?]{
@compat/comp[paragraph], omits a style argument. Also, if
@racket[content] is a list containing a single item, the item by
itself is stored in the resulting @racket[paragraph].}
@defproc[(paragraph-content [p paragraph?]) list?]{
@compat[] Like the normal selector, but if the result would not be a list, it is
coerced to one.
}
@deftogether[(
@defproc[(make-styled-paragraph [content list?] [style any/c]) paragraph?]
@defproc[(styled-paragraph? [v any/c]) boolean?]
@defproc[(styled-paragraph-style [p paragraph?]) style?]
)]{
@compat/comp[paragraph], parses @racket[style] to convert old formats
to the current one. The @racket[styled-paragraph?] predicate and
@racket[styled-paragraph-style] accessor are aliases for
@racket[paragraph?] and @racket[paragraph-style].}
@deftogether[(
@defproc[(make-omitable-paragraph [content list?]) paragraph?]
@defproc[(omitable-paragraph? [v any/c]) boolean?]
)]{
@compat[] Like @racket[make-paragraph], but adds the
@racket['omitable] @tech{style property}. The
@racket[omitable-paragraph?] predicate checks for a paragraph with the
property.}
@defproc[(make-table [style any/c]
[blocksss (listof (listof (or/c (listof block?) (one-of/c 'cont))))])
table?]{
@compat/comp[table], the style is converted, and each cell has a list
of blocks instead of a single block. If any such list has multiple
blocks, they are combined into a @racket[nested-flow].}
@defproc[(table-flowss [table table?])
(listof (listof (or/c (listof block?) (one-of/c 'cont))))]{
@compat[] Like @racket[table-blockss], but adds a list wrapper to be
consistent with @racket[make-table].}
@defproc[(make-itemization [blockss (listof (listof block?))]) itemization?]{
@compat/comp[itemization], omits a style argument.}
@deftogether[(
@defproc[(make-styled-itemization [style any/c]
[blockss (listof (listof block?))]) itemization?]
@defproc[(styled-itemization? [v any/c]) boolean?]
@defproc[(styled-itemization-style [i itemization?]) style?]
)]{
@compat/comp[itemization], parses @racket[style] to convert old
formats to the current one. The @racket[styled-itemization?] predicate
is an alias for @racket[itemization?], and
@racket[styled-itemization-style] is an alias for
@racket[itemization-style].}
@defproc[(make-blockquote [style any/c] [blocks (listof block?)])
nested-flow?]{
@compat[] Like @racket[make-nested-flow], but @racket[style] is
parsed to the current format.}
@deftogether[(
@defproc[(make-auxiliary-table [style any/c]
[blocksss (listof (listof (or/c (listof block?) (one-of/c 'cont))))])
table?]
@defproc[(auxiliary-table? [v any/c]) boolean?]
)]{
@compat[] Like @racket[make-table], but adds the @racket['aux]
@tech{style property}. The @racket[auxiliary-table?] predicate recognizes
tables with the @racket['aux] property.}
@defproc[(make-compound-paragraph [style any/c]
[blocks (listof block?)])
compound-paragraph?]{
@compat/comp[compound-paragraph], parses @racket[style] to convert old
formats to the current one.}
@deftogether[(
@defproc[(make-element [style any/c] [content list?]) element?]
@defproc[(make-toc-element [style any/c] [content list?] [toc-content list?]) toc-element?]
@defproc[(make-target-element [style any/c] [content list?] [tag tag?]) target-element?]
@defproc[(make-toc-target-element [style any/c] [content list?] [tag tag?]) toc-target-element?]
@defproc[(make-toc-target2-element [style any/c] [content list?] [tag tag?] [toc-content content?]) toc-target2-element?]
@defproc[(make-page-target-element [style any/c] [content list?] [tag tag?]) page-target-element?]
@defproc[(make-redirect-target-element [style any/c] [content list?] [tag tag?]
[alt-path path-string?] [alt-anchor string?]) redirect-target-element?]
@defproc[(make-link-element [style any/c] [content list?] [tag tag?]) link-element?]
@defproc[(make-index-element [style any/c] [content list?] [tag tag?]
[plain-seq (and/c pair? (listof string?))]
[entry-seq list?] [desc any/c]) index-element?]
)]{
@compat[] Compared to the normal constructors, parses @racket[style] to convert old
formats to the current one.}
@deftogether[(
@defproc[(element? [v any/c]) boolean?]
@defproc[(element-content [e element?]) list?]
@defproc[(element-style [e element?]) element-style?]
)]{
@compat[] A @tech{content} list is treated as an element by these functions,
and the result of @racket[element-content] is always a list.}
@defproc[(make-aux-element [style any/c] [content list?]) element?]{
@compat[] Like @racket[make-element], but adds the @racket['aux]
@tech{style property}.}
@defproc[(make-hover-element [style any/c] [content list?] [text string?]) element?]{
@compat[] Like @racket[make-element], but adds @racket[hover-property]
containing @racket[text] to the element's style.}
@defproc[(make-script-element [style any/c] [content list?] [type string?]
[script (or/c path-string? (listof string?))]) element?]{
@compat[] Like @racket[make-element], but adds @racket[script-property]
containing @racket[type] and @racket[script] to the element's style.}
@defstruct[with-attributes ([style any/c]
[assoc (listof (cons/c symbol? string?))])]{
@compat[] Used for an @racket[element]'s style to combine a base style with
arbitrary HTML attributes. When the @racket[style] field is itself an
instance of @racket[with-attributes], its content is automatically
flattened into the enclosing @racket[with-attributes] when it is used
(when, e.g., rendering an @racket[element] or @racket[paragraph]).}
@defstruct[target-url ([addr path-string?]
[style any/c])]{
@compat[] Used as a style for an @racket[element]. The @racket[style] at this
layer is a style for the hyperlink.}
@defstruct[image-file ([path (or/c path-string?
(cons/c 'collects (listof bytes?)))]
[scale real?])]{
@compat[] 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].}
@defproc*[([(element->string (element content?)) string?]
[(element->string (element content?) (renderer any/c) (p part?) (info resolve-info?)) string?])]{
@compat[] An alias for @racket[content->string].
}

231
scribble-doc/scribblings/scribble/style.scrbl
View File

@ -1,231 +0,0 @@
#lang scribble/doc
@(require scribble/manual scribble/eval "utils.rkt"
(for-label scribble/manual scribble/eval))
@title[#:tag "reference-style"]{Style Guide}
Consistent style---for terms, typesetting, and prose---makes
documentation clearer. As much as possible, follow the rules listed in
this section. Many of the rules are arbitrary in the sense that a
different choice of rule could work fine, but the only way to make our
documentation consistent is to pick one of the choices.
There are too many rules to absorb easily on a first reading. Re-read
this section after writing documentation for a library or two, and
revisit the section periodically to refresh your memory and check for
new rules.
@section{Prose and Terminology}
In the descriptive body of @racket[defform], @racket[defproc], etc.,
do not start with ``This ...'' Instead, start with a sentence whose
implicit subject is the form or value being described (but only start
the first sentence that way). Capitalize the first word. Thus, the
description will often start with ``Returns'' or ``Produces.'' Refer
to arguments and sub-forms by name.
Do not use the word ``argument'' to describe a sub-form in a syntactic
form; use the term ``sub-form'' instead, reserving ``argument'' for
values or expressions in a function call. Refer to libraries and
languages as such, rather than as ``modules'' (even though the form to
typeset a library or language name is called @racket[racketmodname]).
Do not call an identifier (i.e., a syntactic element) a ``variable''
or a ``symbol.'' Do not use the word ``expression'' for a form that is
a definition or might be a definition; use the word ``form,'' instead.
Prefer ``function'' to ``procedure.''
Use the word ``list'' only when you mean a run-time value consisting
of the empty list and cons cells; use the word ``sequence'' in other
cases, if you must use any word. For example, do not write that
@racket[begin] has a ``list of sub-forms;'' instead, it has a
``sequence of sub-forms.'' Similarly, do not refer to a ``list of
arguments'' in a function call; just write ``arguments'' if possible,
or write ``sequence of argument expressions.'' (Unfortunately,
``@tech[#:doc '(lib
"scribblings/reference/reference.scrbl")]{sequence}'' has acquired a
specific run-time meaning, too, but the collision is less severe than
the historical confusion between lists and other entities in Lisp.)
Avoid cut-and-paste for descriptive text. If two functions are
similar, consider documenting them together with
@racket[deftogether]. To abstract a description, consider using
explicit prose abstraction, such as ``@racket[x] is like @racket[y],
except that ...,'' instead of abstracting the source and instantiating
it multiple times; often, a prose abstraction is clearer to the reader
than a hidden abstraction in the document implementation.
Hyphenate the words ``sub-form'' and ``sub-expression.''
Use ``Windows,'' ``Mac OS X,'' and ``Unix'' for the three
``platforms'' (as opposed to ``systems'') on which Racket runs. Use
``Unix'' as a generic term for Unix-like operating systems---notably
including Linux---other than Mac OS X. Use ``Unix'' even when ``Gtk''
or ``the X11 windowing system'' would be more precisely correct, but
use ``X11'' as adjective when necessary, such as ``X11 display.''
Racket runs ``on'' a platform, as opposed to ``under'' a platform.
@section{Typesetting Code}
Use @racketidfont{id} or a name that ends @racketidfont{-id} in
@racket[defform] to mean an identifier, not @racketidfont{identifier},
@racketidfont{variable}, @racketidfont{name}, or
@racketidfont{symbol}. Similarly, use @racketidfont{expr} or something
that ends @racketidfont{-expr} for an expression position within a
syntactic form. Use @racketidfont{body} for a form (definition or
expression) in an internal-definition position---always followed by
@racket[...+] in a grammar description. Do not use
@racketidfont{expr} for something that isn't exactly an expression,
@racket[id] for something that isn't exactly an identifier, etc.;
instead, use @racket[defform/subs] to define a new non-terminal.
Beware of using @racket[deftogether] to define multiple variants of a
syntactic form or procedure, because each @racket[defform] or
@racket[defproc] creates a definition point, but each form or
procedure should have a single definition point. (Scribble issues a
warning when a binding has multiple definition points.) Instead, use
@racket[defproc*] or @racket[defform*].
For function arguments, use @racket[v] as the meta-variable for ``any
value.'' Use @racket[x] as a meta-variable only for numerical
values. Other conventions include @racket[lst] for a list and
@racket[proc] for a procedure.
Pay attention to the difference between identifiers and meta-variables
when using @racket[racket], especially outside of @racket[defproc] or
@racket[defform]. Prefix a meta-variable with @litchar{_}; for
example,
@verbatim[#:indent 2]|{@racket[(rator-expr rand-expr ...)]}|
would be the wrong way to refer to the grammar of a function call,
because it produces @racket[(rator-expr rand-expr ...)], where
@racketidfont{rator-expr} and @racketidfont{rand-expr} are
typeset as variables. The correct description is
@verbatim[#:indent 2]|{@racket[(_rator-expr _rand-expr ...)]}|
which produces @racket[(_rator-expr _rand-expr ...)], where
@racketidfont{rator-expr} and @racketidfont{rand-expr} are typeset as
meta-variables. The @racket[defproc], @racket[defform], @|etc| forms
greatly reduce this burden in descriptions, since they automatically
set up meta-variable typesetting for non-literal identifiers. In
@racket[defform], be sure to include literal identifiers (i.e., those
not meant as variables, other than the form name being defined) in a
@racket[#:literals] clause.
To typeset an identifier with no particular interpretation---syntax,
variable, meta-variable, etc.---use @racket[racketidfont] (e.g., as in
@racketidfont{rand-expr} above). Otherwise, use @racket[litchar],
not merely @racket[racketfont] or @racket[verbatim], to refer to a
specific sequence of characters.
When a syntactic form synthesizes an identifier from a given
identifier, use a combination of @racket[racketidfont] and
@racket[racket] to describe the identifiers. For example, if
@racket[_id] is combined with @racketidfont{is-} and @racketidfont{?}
to form @racketidfont{is-}@racket[_id]@racketidfont{?}, then implement
that identifier as
@code[#:lang "at-exp racket"]|{@racketidfont{is-}@racket[id]@racketidfont{?}}|.
When using @racket[defform] to describe a syntactic form, don't
confuse the @racket[#:contracts] clause with a grammar
specification. Use @racket[#:contracts] only for expressions within the
syntactic form, and the contract is a run-time constraint---not a
syntactic constraint, such as requiring a sub-form to be an identifier.
Use @racket[defform/subs] for syntactic constraints.
When showing example evaluations, use the REPL-snapshot style:
@verbatim[#:indent 2]|{
@interaction[
(+ 1 2)
]
}|
See also the @racket[scribble/eval] library and @secref["examples-style"].
Use four dots, @litchar{....}, in place of omitted code, since
@litchar{...} means repetition.
@section{Typesetting Prose}
Refrain from referring to documentation ``above'' or ``below,'' and
instead have a hyperlink point to the right place.
In prose, use @litchar{``} and @litchar{''} quotation marks instead of
@litchar{"}. Use @litchar{---} for an em dash, and do not include
spaces on either side. Use American style for quotation marks and punctuation
@; [Eli] BTW, I've asked several people about this, and the general
@; agreement that I've seen is that this is a rather arbitrary rule
@; and there's no harm in doing the more logical thing of putting
@; the punctuations outside quotations and parens. Just like you
@; did at the end of this sentence...
@; [Matthew] See intro of this section.
at the end of quotation marks (i.e., a sentence-terminating period
goes inside the quotation marks). Of course, this rule does not apply
for quotation marks that are part of code.
Do not use a citation reference (as created by @racket[cite]) as a
noun; use it as an annotation.
Do not start a sentence with a Racket variable name, since it is
normally lowercase. For example, use ``The @racket[_thing] argument
is...'' instead of ``@racket[_thing] is...''
Use @racket[etc] for ``@|etc|'' when it does not end a sentence, and
include a comma after ``@|etc|'' unless it ends a sentence of is
followed by other punctuation (such as a parenthesis).
@section{Section Titles}
Capitalize all words except articles (``the,'' ``a,'' etc.),
prepositions, and conjunctions that are not at the start of the title.
A manual title should normally start with a suitable keyword or key
phrase (such as ``Scribble'' for this manual) that is in boldface. If
the key word is primarily an executable name, use @racket[exec]
instead of @racket[bold]. Optionally add further descriptive text in
the title after a colon, where the text starting with the colon is not
in boldface.
@section{Indexing}
Document and section titles, identifiers that are documented with
@racket[defproc], @racket[defform], etc. are automatically indexed, as
are terms defined with @racket[deftech].
Symbols are not indexed automatically. Use @racket[indexed-racket]
instead of @racket[racket] for the instance of a symbol that roughly
defines the use. For an example, try searching for ``truncate'' to
find @racket['truncate] as used with @racket[open-output-file]. Do no
use something like @racket[(index "'truncate")] to index a symbol,
because it will not typeset correctly (i.e., in a fixed-width font
with the color of a literal).
Use @racket[index], @racket[as-index], and @racket[section-index] as a
last resort. Create index entries for terms that are completely
different from terms otherwise indexed. Do not try to index minor
variations of a term or phrase in an attempt to improve search
results; if search fails to find a word or phrase due to a minor
variation, then the search algorithm should be fixed, not the index
entry.
@section[#:tag "examples-style"]{Examples}
Strive to include examples (using @racket[examples]) with the
documentation of every function and syntactic form. When writing
examples, refrain from using nonsense words like ``foo'' and ``bar.''
For example, when documenting @racket[member], resist the temptation
to write
@interaction[
(member "foo" '("bar" "foo" "baz"))
]
and instead write something like
@interaction[
(member "Groucho" '("Harpo" "Groucho" "Zeppo"))
]

140
scribble-doc/scribblings/scribble/tag.scrbl
View File

@ -1,140 +0,0 @@
#lang scribble/doc
@(require scribble/manual "utils.rkt"
(for-label setup/main-collects))
@title[#:tag "tag"]{Tag Utilities}
@declare-exporting[scribble/tag scribble/base]
@defmodule*/no-declare[(scribble/tag)]{The @racketmodname[scribble/tag]
library provides utilities for constructing cross-reference
@tech{tags}. The library is re-exported by
@racketmodname[scribble/base].}
@; ------------------------------------------------------------------------
@defproc[(make-section-tag [name string?]
[#:doc doc-mod-path (or/c module-path? #f) #f]
[#:tag-prefixes tag-prefixes (or/c #f (listof string?)) #f])
tag?]{
Forms a @tech{tag} that refers to a section whose ``tag'' (as provided
by the @racket[#:tag] argument to @racket[section], for example) is
@racket[name]. If @racket[doc-mod-path] is provided, the @tech{tag}
references a section in the document implemented by
@racket[doc-mod-path] from outside the document. Additional tag
prefixes (for intermediate sections, typically) can be provided as
@racket[tag-prefixes].}
@defproc[(make-module-language-tag [lang symbol?]) tag?]{
Forms a @tech{tag} that refers to a section
that contains @racket[defmodulelang] for the language
@racket[lang].
}
@defproc[(taglet? [v any/c]) boolean?]{
Returns @racket[#t] if @racket[v] is a @tech{taglet}, @racket[#f]
otherwise.
A @deftech{taglet} is a value that can be combined with a symbol via
@racket[list] to form a @tech{tag}, but that is not a
@racket[generated-tag]. A @tech{taglet} is therefore useful as a piece
of a @tech{tag}, and specifically as a piece of a tag that can gain a
prefix (e.g., to refer to a section of a document from outside the
document).}
@defproc*[([(doc-prefix [mod-path (or/c #f module-path?)]
[taglet taglet?])
taglet?]
[(doc-prefix [mod-path (or/c #f module-path?)]
[extra-prefixes (or/c #f (listof taglet?))]
[taglet taglet?])
taglet?])]{
Converts part of a cross-reference @tech{tag} that would work within a
document implemented by @racket[mod-path] to one that works from
outside the document, assuming that @racket[mod-path] is not
@racket[#f]. That is, @racket[mod-path] is converted to a
@tech{taglet} and added as prefix to an existing @racket[taglet].
If @racket[extra-prefixes] is provided, then its content is added as a
extra prefix elements before the prefix for @racket[mod-path] is
added. A @racket[#f] value for @racket[extra-prefixes] is equivalent
to @racket['()].
If @racket[mod-path] is @racket[#f], then @racket[taglet] is returned
without a prefix (except adding @racket[extra-prefixes], if provided).}
@defproc[(module-path-prefix->string [mod-path module-path?]) string?]{
Converts a module path to a string by resolving it to a path, and
using @racket[path->main-collects-relative].}
@defproc[(module-path-index->taglet [mpi module-path-index?]) taglet?]{
Converts a module path index to a @tech{taglet}---a normalized
encoding of the path as an S-expression---that is interned via
@racket[intern-taglet].
The string form of the @tech{taglet} is used as prefix in a @tech{tag}
to form cross-references into the document that is implemented by the
module referenced by @racket[mpi].}
@defproc[(intern-taglet [v any/c]) any/c]{
Returns a value that is @racket[equal?] to @racket[v], where multiple
calls to @racket[intern-taglet] for @racket[equal?] @racket[v]s
produce the same (i.e., @racket[eq?]) value.}
@defproc[(definition-tag->class/interface-tag [definition-tag definition-tag?])
class/interface-tag?]{
Constructs a tag like @racket[definition-tag], except that
it matches documentation for the class. If @racket[definition-tag]
doesn't document a class or interface, this function still returns
the tag that the class or interface documentation would have had,
as if @racket[definition-tag] had documented a class or interface.
@history[#:added "1.11"]
}
@defproc[(class/interface-tag->constructor-tag [class/interface-tag class/interface-tag?])
constructor-tag?]{
Constructs a tag like @racket[definition-tag], except that
it matches documentation for the constructor of the class.
@history[#:added "1.11"]
}
@defproc[(get-class/interface-and-method [method-tag method-tag?])
(values symbol? symbol?)]{
Returns the class name and method name (respectively) for the method documented
by the docs at @racket[method-tag].
@history[#:added "1.11"]
}
@defproc[(definition-tag? [v any/c]) boolean?]{
Recognizes definition tags. If @racket[(definition-tag? _v)] is
@racket[#t], then so is @racket[(tag? _v)].
@history[#:added "1.11"]
}
@defproc[(class/interface-tag? [v any/c]) boolean?]{
Recognizes class or interface tags. If @racket[(class/interface-tag? _v)] is
@racket[#t], then so is @racket[(tag? _v)].
@history[#:added "1.11"]
}
@defproc[(method-tag? [v any/c]) boolean?]{
Recognizes method tags. If @racket[(method-tag? _v)] is
@racket[#t], then so is @racket[(tag? _v)].
@history[#:added "1.11"]
}
@defproc[(constructor-tag? [v any/c]) boolean?]{
Recognizes class constructor tags. If @racket[(constructor-tag? _v)] is
@racket[#t], then so is @racket[(tag? _v)].
@history[#:added "1.11"]
}

1362
scribble-doc/scribblings/scribble/text.scrbl
View File

File diff suppressed because it is too large Load Diff

229
scribble-doc/scribblings/scribble/utils.rkt
View File

@ -1,229 +0,0 @@
#lang racket/base
(require scribble/core
scribble/html-properties
scribble/manual
(prefix-in racket: scribble/racket)
(prefix-in scribble: scribble/reader))
(define-syntax bounce-for-label
(syntax-rules (all-except)
[(_ (all-except mod (id ...) (id2 ...)))
(begin (require (for-label (except-in mod id ...)))
(provide (for-label (except-out (all-from-out mod) id2 ...))))]
[(_ mod) (begin (require (for-label mod))
(provide (for-label (all-from-out mod))))]
[(_ mod ...) (begin (bounce-for-label mod) ...)]))
(bounce-for-label (all-except racket (abstract link) ())
scribble/core
scribble/base-render
scribble/decode
scribble/manual
scribble/racket
scribble/html-properties
scribble/latex-properties
scribble/bnf)
(provide scribble-examples litchar/lines doc-render-examples)
(define (as-flow e)
(if (block? e) e (make-paragraph plain (list e))))
(define (litchar/lines . strs)
(let ([strs (regexp-split #rx"\n" (apply string-append strs))])
(if (= 1 (length strs))
(litchar (car strs))
(make-table
plain
(map (lambda (s) ; the nbsp is needed for IE
(list (as-flow (if (string=? s "") 'nbsp (litchar s)))))
strs)))))
(define spacer (hspace 2))
(define ((norm-spacing base) p)
(cond [(and (syntax->list p) (not (null? (syntax-e p))))
(let loop ([e (syntax->list p)]
[line (syntax-line (car (syntax-e p)))]
[pos base]
[second #f]
[accum null])
(if (null? e)
(datum->syntax
p (reverse accum)
(list (syntax-source p) (syntax-line p) base (add1 base)
(- pos base))
p)
(let* ([v ((norm-spacing (if (= line (syntax-line (car e)))
pos
(or second pos)))
(car e))]
[next-pos (+ (syntax-column v) (syntax-span v) 1)])
(loop (cdr e)
(syntax-line v)
next-pos
(or second next-pos)
(cons v accum)))))]
[else (datum->syntax
p (syntax-e p)
(list (syntax-source p) (syntax-line p) base (add1 base) 1)
p)]))
(define (scribble-examples . lines)
(define reads-as (make-paragraph plain (list spacer "reads as" spacer)))
(let* ([lines (apply string-append lines)]
[p (open-input-string lines)])
(port-count-lines! p)
(let loop ([r '()] [newlines? #f])
(regexp-match? #px#"^[[:space:]]*" p)
(let* ([p1 (file-position p)]
[stx (scribble:read-syntax #f p)]
[p2 (file-position p)])
(if (not (eof-object? stx))
(let ([str (substring lines p1 p2)])
(loop (cons (list str stx) r)
(or newlines? (regexp-match? #rx#"\n" str))))
(let* ([r (reverse r)]
[r (if newlines?
(cdr (apply append (map (lambda (x) (list #f x)) r)))
r)])
(make-table
plain
(map (lambda (x)
(let ([@expr (if x (litchar/lines (car x)) "")]
[sexpr (if x
(racket:to-paragraph
((norm-spacing 0) (cadr x)))
"")]
[reads-as (if x reads-as "")])
(map as-flow (list spacer @expr reads-as sexpr))))
r))))))))
;; stuff for the scribble/text examples
(require racket/list (for-syntax racket/base racket/list))
(define max-textsample-width 45)
(define (textsample-verbatim-boxes line in-text out-text more)
(define (split str) (regexp-split #rx"\n" str))
(define strs1 (split in-text))
(define strs2 (split out-text))
(define strsm (map (compose split cdr) more))
(define (str->elts str)
(let ([spaces (regexp-match-positions #rx"(?:^| ) +" str)])
(if spaces
(list* (str->elts (substring str 0 (caar spaces)))
(smaller (hspace (- (cdar spaces) (caar spaces))))
(str->elts (substring str (cdar spaces))))
(list (smaller (make-element 'tt str))))))
(define (make-line str)
(list (as-flow (if (equal? str "")
(smaller (hspace 1))
(str->elts str)))))
(define (make-box strs [file #f])
(nested #:style 'code-inset
(let ([t (make-table plain (map make-line strs))])
(if file
(filebox file t)
t))))
(define filenames (map car more))
(define indent (let ([d (- max-textsample-width
(for*/fold ([m 0])
([s (in-list (cons strs1 strsm))]
[s (in-list s)])
(max m (string-length s))))])
(if (negative? d)
(error 'textsample-verbatim-boxes
"left box too wide for sample at line ~s" line)
(make-element 'tt (list (hspace d))))))
;; Note: the font-size property is reset for every table, so we need it
;; everywhere there's text, and they don't accumulate for nested tables
(values
(make-table
(make-style #f
(list (make-table-columns (list (make-style #f '(left top))))))
(cons (list (as-flow (make-box strs1)))
(map (lambda (file strs)
(list (as-flow (make-box strs file))))
filenames strsm)))
(make-box strs2)))
(define (textsample line in-text out-text more)
(define-values (box1 box2)
(textsample-verbatim-boxes line in-text out-text more))
(make-table
(make-style #f (list (make-table-columns (list (make-style #f '(left vcenter))
(make-style "Short" '(left vcenter))
(make-style #f '(left vcenter))))))
(list (map as-flow (list box1 (make-paragraph plain '(nbsp rarr nbsp)) box2)))))
(define-for-syntax tests-ids #f)
(provide initialize-tests)
(define-syntax (initialize-tests stx)
(set! tests-ids (map (lambda (x) (datum->syntax stx x stx))
'(tests add-to-tests)))
(with-syntax ([(tests add-to-tests) tests-ids])
#'(begin (provide tests)
(define-values (tests add-to-tests)
(let ([l '()])
(values (lambda () (reverse l))
(lambda (x) (set! l (cons x l)))))))))
(provide example)
(define-syntax (example stx)
(define sep-rx #px"^---[*]{3}---(?: +(.*))?$")
(define file-rx #rx"^[a-z0-9_.+-]+$")
(define-values (body hidden?)
(syntax-case stx ()
[(_ #:hidden x ...) (values #'(x ...) #t)]
[(_ x ...) (values #'(x ...) #f)]))
(let loop ([xs body] [text '(#f)] [texts '()])
(syntax-case xs ()
[("\n" sep "\n" . xs)
(and (string? (syntax-e #'sep)) (regexp-match? sep-rx (syntax-e #'sep)))
(let ([m (cond [(regexp-match sep-rx (syntax-e #'sep)) => cadr]
[else #f])])
(if (and m (not (regexp-match? file-rx m)))
(raise-syntax-error #f "bad filename specified" stx #'sep)
(loop #'xs
(list (and m (datum->syntax #'sep m #'sep #'sep)))
(cons (reverse text) texts))))]
[(x . xs) (loop #'xs (cons #'x text) texts)]
[() (let ([texts (reverse (cons (reverse text) texts))]
[line (syntax-line stx)])
(define-values (files i/o) (partition car texts))
(unless ((length i/o) . = . 2)
(raise-syntax-error
'example "need at least an input and an output block" stx))
(with-syntax ([line line]
[((in ...) (out ...)) (map cdr i/o)]
[((file text ...) ...) files]
[add-to-tests (cadr tests-ids)])
(quasisyntax/loc stx
(let* ([in-text (string-append in ...)]
[out-text (string-append out ...)]
[more (list (cons file (string-append text ...)) ...)])
(add-to-tests (list line in-text out-text more))
#,(if hidden? #'""
#'(textsample line in-text out-text more))))))]
[_ (raise-syntax-error #f "no separator found in example text")])))
(provide ltx ltxe ltxd)
(define (ltx s) (tt "\\" s)) ; command
(define (ltxe s) (tt s)) ; enviornment
(define (ltxd n s)
(make-element #f (cons (index (list s) (ltx s))
(for/list ([i (in-range n)]) (tt "{}")))))
;; Utility to render examples of scribble documentation forms
;; Note: it would be nice if this abstracted over the codeblock
;; that usually comes along with this too, but that's hard
;; because there's a read-time distinction between [...]
;; and |{...}|.
(define-syntax-rule (doc-render-examples e ...)
(nested "Renders like:\n"
(nested #:style 'inset (nested #:style 'inset e ...))))

236
scribble-doc/scribblings/scribble/xref.scrbl
View File

@ -1,236 +0,0 @@
#lang scribble/doc
@(require scribble/manual "utils.rkt"
(for-label scribble/xref
scribble/base-render
scribble/html-render
setup/xref))
@title[#:tag "xref"]{Cross-Reference Utilities}
@defmodule[scribble/xref]{The @racketmodname[scribble/xref] library
provides utilities for querying cross-reference information that was
collected from a document build.}
@; ------------------------------------------------------------------------
@defproc[(xref? [v any/c]) boolean?]{
Returns @racket[#t] if @racket[v] is a cross-reference record created
by @racket[load-xref], @racket[#f] otherwise.}
@defproc[(load-xref [sources (listof (-> (or/c any/c (-> list?))))]
[#:demand-source demand-source
(tag? -> (or/c (-> any/c) #f))
(lambda (_tag) #f)]
[#:render% using-render% (implementation?/c render<%>)
(render-mixin render%)]
[#:root root-path (or/c path-string? false/c) #f]
[#:doc-id doc-id-str (or/c path-string? false/c) #f])
xref?]{
Creates a cross-reference record given a list of functions,
@racket[sources].
Let @racket[_source] be a function in @racket[sources]. The
@racket[_source] function normally returns serialized information,
@racket[_info], which was formerly obtained from @xmethod[render<%>
serialize-info]. The result of @racket[_source] can optionally be
another function, which is in turn responsible for returning a list of
@racket[_info]s. Finally, each @racket[_info] can be either serialized
information, a @racket[#f] to be ignored, or a value produced by
@racket[make-data+root] or @racket[make-data+root+doc-id], from which
@racket[_data] part is used as serialized information, the
@racket[_root] part overrides @racket[root-path] for deserialization,
and the @racket[_doc-id] part (if any) overrides
@racket[doc-id-string] to identify the source document.
The @racket[demand-source] function can effectively add a new source
to @racket[sources] in response to a search for information on the
given tag. The @racket[demand-source] function returns @racket[#f]
to indicate that no new sources satisfy the given tag.
Since the format of serialized information is specific to a rendering
class, the optional @racket[using-render%] argument accepts the
relevant class. It defaults to HTML rendering, partly because
HTML-format information is usable by other formats (including
Latex/PDF and text).
If @racket[root-path] is not @racket[#f], then file paths that are
serialized as relative to an instantiation-supplied @racket[root-path]
are deserialized as relative instead to the given @racket[root-path],
but a @racket[make-data+root] result for any @racket[_info] supplies
an alternate path for deserialization of the @racket[_info]'s
@racket[_data].
If @racket[doc-id-str] is not @racket[#f], it identifies each
cross-reference entry as originating from @racket[doc-id-str]. This
identification is used when a rendering link to the cross-reference
entry as an external query; see the @racket[set-external-tag-path]
method of @racket[render-mixin].
Use @racket[load-collections-xref] from @racketmodname[setup/xref] to
get all cross-reference information for installed documentation.
@history[#:changed "1.1" @elem{Added the @racket[#:doc-id] argument.}]}
@defproc[(xref-binding->definition-tag [xref xref?]
[binding (or/c identifier?
(list/c (or/c module-path?
module-path-index?)
symbol?)
(listof module-path-index?
symbol?
module-path-index?
symbol?
(one-of/c 0 1)
(or/c exact-integer? false/c)
(or/c exact-integer? false/c)))]
[mode (or/c exact-integer? false/c)])
(or/c tag? false/c)]{
Locates a tag in @racket[xref] that documents a module export. The
binding is specified in one of several ways, as described below; all
possibilities encode an exporting module and a symbolic name. The name
must be exported from the specified module. Documentation is found
either for the specified module or, if the exported name is
re-exported from other other module, for the other module
(transitively).
The @racket[mode] argument specifies the relevant phase level for the
binding. The @racket[binding] is specified in one of four ways:
@itemize[
@item{If @racket[binding] is an identifier, then
@racket[identifier-binding] is used with @racket[mode] to
determine the binding.}
@item{If @racket[binding] is a two-element list, then the first
element provides the exporting module and the second the
exported name. The @racket[mode] argument is effectively
ignored.}
@item{If @racket[binding] is a seven-element list, then it corresponds
to a result from @racket[identifier-binding] using
@racket[mode].}
@item{If @racket[binding] is a five-element list, then the first
element is as for the two-element-list case, and the remain
elements are as in the last four elements of the seven-element
case.}
]
If a documentation point exists in @racket[xref], a tag is returned,
which might be used with @racket[xref-tag->path+anchor] or embedded in
a document rendered via @racket[xref-render]. If no definition point
is found in @racket[xref], the result is @racket[#f].}
@defproc[(xref-tag->path+anchor [xref xref?]
[tag tag?]
[#:external-root-url root-url (or/c string? #f) #f]
[#:render% using-render% (implementation?/c render<%>)
(render-mixin render%)])
(values (or/c false/c path?)
(or/c false/c string?))]{
Returns a path and anchor string designated by the key @racket[tag]
according the cross-reference @racket[xref]. The first result is
@racket[#f] if no mapping is found for the given tag. The second
result is @racket[#f] if the first result is @racket[#f], and it can
also be @racket[#f] if the tag refers to a page rather than a specific
point in a page.
If @racket[root-url] is provided, then references to documentation in
the main installation are redirected to the given URL.
The optional @racket[using-render%] argument is as for
@racket[load-xref].}
@defproc[(xref-tag->index-entry [xref xref?] [tag tag?])
(or/c false/c entry?)]{
Extract an @racket[entry] structure that provides addition information
about the definition (of any) referenced by @racket[tag]. This
function can be composed with @racket[xref-binding->definition-tag] to
obtain information about a binding, such as the library that exports
the binding and its original name.}
@defproc[(xref-render [xref xref?]
[doc part?]
[dest (or/c path-string? false/c)]
[#:render% using-render% (implemenation?/c render<%>)
(render-mixin render%)]
[#:refer-to-existing-files? use-existing? any/c (not dest)])
(or/c void? any/c)]{
Renders @racket[doc] using the cross-reference info in @racket[xref]
to the destination @racket[dest]. For example, @racket[doc] might be a
generated document of search results using link tags described in
@racket[xref].
If @racket[dest] is @racket[#f], no file is written, and the result is
an X-expression for the rendered page. Otherwise, the file
@racket[dest] is written and the result is @|void-const|.
The optional @racket[using-render%] argument is as for
@racket[load-xref]. It determines the kind of output that is
generated.
If @racket[use-existing?] is true, then files referenced during
rendering (such as image files) are referenced from their existing
locations, instead of copying to the directory of @racket[dest].}
@defproc[(xref-transfer-info [renderer (is-a?/c render<%>)]
[ci collect-info?]
[xref xref?])
void?]{
Transfers cross-reference information to @racket[ci], which is the
initially collected information from @racket[renderer].}
@defproc[(xref-index [xref xref?]) (listof entry?)]{
Converts indexing information @racket[xref] into a list of
@racket[entry] structures.}
@defstruct[entry ([words (and/c (listof string?) cons?)]
[content list?]
[tag tag?]
[desc any/c])]{
Represents a single entry in a Scribble document index.
The @racket[words] list corresponds to
@racket[index-element-plain-seq]. The @racket[content] list
corresponds to @racket[index-element-entry-seq]. The @racket[desc]
value corresponds to @racket[index-element-desc]. The @racket[tag] is
the destination for the index link into the main document.}
@deftogether[(
@defproc[(data+root? [v any/c]) boolean?]
@defproc[(make-data+root [data any/c] [root (or/c #f path-string?)]) data+root?]
)]{
A value constructed by @racket[make-data+root] can be returned by a
source procedure for @racket[load-xref] to specify a path used for
deserialization.}
@deftogether[(
@defproc[(data+root+doc-id? [v any/c]) boolean?]
@defproc[(make-data+root+doc-id [data any/c] [root (or/c #f path-string?)] [doc-id string?]) data+root+doc-id?]
)]{
Extends @racket[make-data+root+doc-id] to support an
document-identifying string (see @racket[load-xref]).
@history[#:added "1.1"]}

244
scribble-doc/scriblib/scribblings/autobib.scrbl
View File

@ -1,244 +0,0 @@
#lang scribble/manual
@(require (for-label scribble/struct
scriblib/autobib
scheme/base
scheme/contract))
@title[#:tag "autobib"]{Bibliographies}
@defmodule[scriblib/autobib]
This library provides support for bibliography management in a Scribble
document. The @racket[define-cite] form is used to bind procedures
that create in-line citations and generate the bibilography in the
document.
Individual bibliography entries are created with the @racket[make-bib]
function. See below for an example.
@codeblock|{
#lang scribble/base
@(require scriblib/autobib)
@(define-cite ~cite citet generate-bibliography)
@(define plt-tr1
(make-bib
#:title "Reference: Racket"
#:author (authors "Matthew Flatt" "PLT")
#:date "2010"
#:location (techrpt-location #:institution "PLT Inc."
#:number "PLT-TR-2010-1")
#:url "http://racket-lang.org/tr1/"))
Racket is fun@~cite[plt-tr1].
@(generate-bibliography)
}|
For citations that reference a page number or section, the @racket[in-bib]
function can be used. For example, the following snippet:
@codeblock[#:keep-lang-line? #f]|{
#lang scribble/base
Racket has a contract library.@~cite[(in-bib plt-tr1 ", §8")]
}|
includes a citation to section 8 of the Racket reference.
@defform/subs[(define-cite ~cite-id citet-id generate-bibliography-id
option ...)
([option (code:line #:style style-expr)
(code:line #:disambiguate disambiguator-expr)
(code:line #:spaces spaces-expr)
(code:line #:render-date-bib render-date-expr)
(code:line #:render-date-cite render-date-expr)
(code:line #:date<? date-compare-expr)
(code:line #:date=? date-compare-expr)])
#:contracts ([style-expr (or/c author+date-style number-style)]
[spaces-expr number]
[disambiguator-expr (or/c #f (-> exact-nonnegative-integer? element?))]
[render-date-expr (or/c #f (-> date? element?))]
[date-compare-expr (or/c #f (-> date? date? boolean?))])]{
Binds @racket[~cite-id], @racket[citet-id], and
@racket[generate-bibliography-id], which share state to accumulate and
render citations.
The function bound to @racket[~cite-id] produces a citation referring
to one or more bibliography entries with a preceding non-breaking
space, by default sorting the entries to match the bibliography order.
It has the contract
@racketblock[
(->* (bib?) (#:sort? any/c) #:rest (listof bib?) element?)
]
The function bound to @racket[citet-id] generates an element suitable
for use as a noun---referring to a document or its author---for one
or more bibliography entries which have the same authors. It has the contract
@racketblock[
(->* (bib?) () #:rest (listof bib?) element?)
]
The function bound to @racket[generate-bibliography-id] generates the
section for the bibliography. It has the contract
@racketblock[
(->* () (#:tag string? #:sec-title string?) part?)
]
The default value for the @racket[#:tag] argument is @racket["doc-bibliography"]
and for @racket[#:sec-title] is @racket["Bibliography"].
The optional @racket[spaces-expr] determines the number of blank lines that appear
between citations. The default number of lines is 1.
The optional @racket[style-expr] determines the way that citations and
the bibliography are rendered.@margin-note*{Programmer-defined styles
may be supported in the future.} Currently, two built-in style are
provided, and @racket[author+date-style] is the default.
For @racket[author+date-style],
if two citations' references would render the same (as judged by equal
authors and dates that are considered the same) but are different, the
optionally provided function from @racket[disambiguator-expr] is used
to add an extra element after the date; the default disambiguator adds
@litchar{a}, @litchar{b}, @etc until @litchar{z}, and anything more
ambiguous raises an exception. Date comparison is controlled by
@racket[date-compare-expr]s. Dates in citations and dates in the
bibliography may be rendered differently, as specified by the
optionally given @racket[render-date-expr] functions.}
@deftogether[(
@defthing[author+date-style any/c]
@defthing[number-style any/c]
)]{
Styles for use with @racket[define-cite].}
@defproc[(bib? [v any/c]) boolean?]{
Returns @racket[#t] if @racket[v] is a value produced by
@racket[make-bib] or @racket[in-bib], @racket[#f] otherwise.}
@defproc[(make-bib [#:title title any/c]
[#:author author any/c #f]
[#:is-book? is-book? any/c #f]
[#:location location any/c #f]
[#:date date (or/c #f date? exact-nonnegative-integer? string?) #f]
[#:url url string? #f]
[#:note note any/c #f])
bib?]{
Produces a value that represents a document to cite. Except for
@racket[is-book?] and @racket[url], the arguments are used as
content, except that @racket[#f] means that the information is not
supplied. Functions like @racket[proceedings-location],
@racket[author-name], and @racket[authors] help produce elements in a
standard format.
Dates are internally represented as @racket[date] values, so a @racket[date]
may be given, or a number or string that represent the year.
An element produced by a function like @racket[author-name] tracks
first, last names, and name suffixes separately, so that names can be
ordered and rendered correctly. When a string is provided as an author
name, the last non-empty sequence of alphabetic characters or
@litchar["-"] after a space is treated as the author name, and the
rest is treated as the first name.}
@defproc[(in-bib [orig bib?] [where string?]) bib?]{
Extends a bib value so that the rendered citation is suffixed with
@racket[where], which might be a page or chapter number.}
@defproc[(proceedings-location [location any/c]
[#:pages pages (or (list/c any/c any/c) #f) #f]
[#:series series any/c #f]
[#:volume volume any/c #f])
element?]{
Combines elements to generate an element that is suitable for
describing a paper's location within a conference or workshop
proceedings.}
@defproc[(journal-location [title any/c]
[#:pages pages (or (list/c any/c any/c) #f) #f]
[#:number number any/c #f]
[#:volume volume any/c #f])
element?]{
Combines elements to generate an element that is suitable for
describing a paper's location within a journal.}
@defproc[(book-location [#:edition edition any/c #f]
[#:publisher publisher any/c #f])
element?]{
Combines elements to generate an element that is suitable for
describing a book's location.}
@defproc[(techrpt-location [#:institution institution edition any/c]
[#:number number any/c])
element?]{
Combines elements to generate an element that is suitable for
describing a technical report's location.}
@defproc[(dissertation-location [#:institution institution edition any/c]
[#:degree degree any/c "PhD"])
element?]{
Combines elements to generate an element that is suitable for
describing a dissertation.}
@defproc[(author-name [first any/c]
[last any/c]
[#:suffix suffix any/c #f])
element?]{
Combines elements to generate an element that is suitable for
describing an author's name, especially where the last name is not
merely a sequence of ASCII alphabet letters or where the name has a
suffix (such as ``Jr.'').}
@defproc[(authors [name content?] [names content?] ...) element?]{
Combines multiple author elements into one, so that it is rendered and
alphabetized appropriately. Any of @racket[name] or @racket[names]
that are strings are
parsed in the same way as by @racket[make-bib].}
@defproc[(org-author-name [name any/c]) element?]{
Converts an element for an organization name to one suitable for use
as a bib-value author.}
@defproc[(other-authors) element?]{
Generates an element that is suitable for use as a ``others'' author.
When combined with another author element via @racket[authors], the
one created by @racket[other-authors] renders as ``et al.''}
@defproc[(editor [name name/c]) element?]{
Takes an author-name element and create one that represents the editor
of a collection. If a @racket[name] is a string, it is parsed in the
same way as by @racket[make-bib].}
@defparam[abbreviate-given-names abbreviate? any/c]{
Shortens given names in calls to @racket[author] and @racket[make-bib]
to just the first initial when the parameter value is not @racket[#f].
Otherwise, does not change the author names.
Defaults to @racket[#f].
@history[#:added "1.5"]
}

54
scribble-doc/scriblib/scribblings/bibtex.scrbl
View File

@ -1,54 +0,0 @@
#lang scribble/manual
@(require (for-label scribble/struct
scriblib/bibtex
scriblib/autobib
racket/base
racket/contract))
@title[#:tag "bibtex"]{BibTeX Bibliographies}
@defmodule[scriblib/bibtex]
@defform[(define-bibtex-cite bib-pth ~cite-id citet-id generate-bibliography-id
option ...)]{
Expands into:
@racketblock[
(begin
(define-cite autobib-cite autobib-citet generate-bibliography-id
option ...)
(define-bibtex-cite* bib-pth
autobib-cite autobib-citet
~cite-id citet-id))]
}
@defform[(define-bibtex-cite* bib-pth autobib-cite autobib-citet
~cite-id citet-id)]{
Parses @racket[bib-pth] as a BibTeX database, and augments
@racket[autobib-cite] and @racket[autobib-citet] into
@racket[~cite-id] and @racket[citet-id] functions so that rather than
accepting @racket[bib?] structures, they accept citation key strings.
Each string is broken along spaces into citations keys that are looked up in the BibTeX database and turned into @racket[bib?] structures.
The only BibTeX entries that are supported are: @litchar{misc},
@litchar{book}, @litchar{article}, @litchar{inproceedings},
@litchar{webpage}, @litchar{mastersthesis}, and @litchar{techreport}.
}
@defstruct*[bibdb ([raw (hash/c string? (hash/c string? string?))]
[bibs (hash/c string? bib?)])]{
Represents a BibTeX database. The @racket[_raw] hash table maps the labels in the file to hash tables of the attributes and their values. The @racket[_bibs] hash table maps the same labels to Scribble data-structures representing the same information.
}
@defproc[(path->bibdb [path path-string?])
bibdb?]{
Parses a path into a BibTeX database.
}
@defproc[(bibtex-parse [ip input-port?])
bibdb?]{
Parses an input port into a BibTeX database.
}

129
scribble-doc/scriblib/scribblings/figure.scrbl
View File

@ -1,129 +0,0 @@
#lang scribble/manual
@(require (for-label scribble/core
scribble/decode
scriblib/figure
scheme/base
scheme/contract))
@(define-syntax-rule (sn s) @racket[s])
@title[#:tag "figure"]{Figures}
@defmodule[scriblib/figure]
@deftogether[(
@defproc[(figure [tag string?] [caption content?]
[p pre-flow?] ...
[#:style style style? center-figure-style]
[#:continue? continue? any/c #f])
block?]
@defproc[(figure* [tag string?] [caption content?]
[p pre-flow?] ...
[#:style style style? center-figure-style]
[#:continue? continue? any/c #f])
block?]
@defproc[(figure** [tag string?] [caption content?]
[p pre-flow?] ...
[#:style style style? center-figure-style]
[#:continue? continue? any/c #f])
block?]
@defproc[(figure-here [tag string?] [caption content?]
[pre-flow pre-flow?] ...
[#:style style style? center-figure-style]
[#:continue? continue? any/c #f])
block?]
)]{
Creates a figure. The given @racket[tag] is for use with
@racket[figure-ref] or @racket[Figure-ref]. The @racket[caption] is an
element. The @racket[pre-flow] is decoded as a flow.
For HTML output, the @racket[figure] and @racket[figure*] functions
are the same, while @racket[figure**] allows the content to be wider
than the document body. For two-column Latex output, @racket[figure*]
and @racket[figure**] generate a figure that spans columns.
For Latex output, @racket[figure-here] generates a figure to be included at
the position in the output text where the @racket[figure-here] occurs
in the source text. For HTML output, all @racket[figure] variants
place the figure where the use appears in the source text.
By default, @racket[style] is set so that the content of the figure is
centered. Use @racket[left-figure-style], @racket[center-figure-style],
or @racket[right-figure-style] to specify the alignment.
If @racket[continue?] is a true value, then the figure counter is not
incremented.}
@deftogether[(
@defthing[left-figure-style style?]
@defthing[center-figure-style style?]
@defthing[right-figure-style style?]
@defthing[left style?]
)]{
Implements figure alignments.
The @racket[left] binding is a synonym for @racket[left-figure-style],
provided for backward compatibility.}
@defproc[(figure-ref [tag string?] ...+) element?]{
Generates a reference to one or more figures, using a lowercase word ``figure''.}
@defproc[(Figure-ref [tag string?] ...+) element?]{
Generates a reference to one or more figures, capitalizing the word ``Figure''.}
@defproc[(Figure-target [tag string?]
[#:continue? continue? any/c #f])
element?]{
Generates a new figure label. This function is normally not used
directly, since it is used by @racket[figure].}
@defproc[(suppress-floats) element?]{
Produces an empty element that renders in Latex as
@tt{\suppressfloats}, which discourages the placement of figures in
the column or page of the surrounding text.}
@section{Configuring Output}
Output uses the following style names, which can be adjusted in an
overriding @filepath{.css} or @filepath{.tex} specification:
@itemize[
@item{@sn{Figure}, @sn{FigureMulti}, @sn{FigureMultiWide}, or
@sn{HereFigure} --- used for the outer of three
@racket[nested-flow]s for a figure, depending on whether
@racket[figure], @racket[figure*], @racket[figure**], or
@racket[figure-here] is used to generate the figure.}
@item{@sn{Leftfigure}, @sn{Centerfigure}, or @sn{Rightfigure} ---
used for the middle of three @racket[nested-flow]s for a
figure, depending on the specified style.}
@item{@sn{FigureInside} --- used for the inner of three
@racket[nested-flow]s for a figure.}
@item{@sn{Legend} --- Wraps the caption for a figure.}
@item{@sn{LegendContinued} --- Wraps the caption for a figure that
does not increment the figure counter.}
@item{@sn{FigureTarget} --- Wraps the label anchor and text within a
figure's caption. For Latex output, the corresponding command
is given a second argument, which is just the generated label
(used with @tt{\label} in the command's first argument).}
@item{@sn{FigureRef} --- Wraps a reference to a figure. For Latex
output, the corresponding command is given a second argument,
which is just the target label.}
]

33
scribble-doc/scriblib/scribblings/footnote.scrbl
View File

@ -1,33 +0,0 @@
#lang scribble/manual
@(require (for-label scribble/struct
scriblib/footnote
scheme/base
scheme/contract))
@title[#:tag "footnotes"]{Footnotes}
@defmodule[scriblib/footnote]
@defproc[(note [pre-content pre-content?] ...) element?]{
Creates a margin note for HTML and a footnote for Latex/PDF output.}
@defform[(define-footnote footnote-id footnote-part-id)]{
Binds @racket[footnote-id] to a form like @racket[note] that generates
a footnote in HTML output as well as Latex/PDF output. To trigger the
HTML output of the footnotes that are registered through
@racket[footnote-id], the function bound to @racket[footnote-part-id]
must be called at a position that corresponds the bottom of the HTML
page. (The generated section will not show a title or appear in a
table of contents; it will look like a footnote area.)
Beware that any content passed to @racket[footnote-id] will occur
twice in at least an intermediate form of the document, and perhaps
also in the rendered form of the document. Consequently, the content
passed to @racket[footnote-id] should not bind link targets or include
other one-time declarations.}

81
scribble-doc/scriblib/scribblings/gui-eval.scrbl
View File

@ -1,81 +0,0 @@
#lang scribble/manual
@(require (for-label scribble/eval scriblib/gui-eval))
@title[#:tag "gui-eval"]{Examples Using the GUI Toolbox}
@defmodule[scriblib/gui-eval]{The
@racketmodname[scriblib/gui-eval] library support example
evaluations that use @racketmodname[racket/gui] facilities (as opposed
to just @racketmodname[racket/draw]) to generate text and image results.}
The trick is that @racketmodname[racket/gui] is not generally
available when rendering documentation, because it requires a GUI
context. Text and image output is rendered to an image file when the
@envvar{MREVAL} environment variable is set, so run the enclosing
document once with the environment varibale to generate the
images. Future runs (with the environment variable unset) use the
generated image.
@deftogether[(
@defform*[((gui-interaction datum ...)
(gui-interaction
#:eval+opts the-eval get-predicate? get-render
get-get-width get-get-height
datum ...))
]
@defform*[((gui-interaction-eval datum ...)
(gui-interaction-eval
#:eval+opts the-eval get-predicate? get-render
get-get-width get-get-height
datum ... ))]
@defform*[((gui-interaction-eval-show datum ...)
(gui-interaction-eval-show
#:eval+opts the-eval get-predicate? get-render
get-get-width get-get-height
datum ...))]
@defform*[((gui-racketblock+eval datum ...)
(gui-racketblock+eval
#:eval+opts the-eval get-predicate? get-render
get-get-width get-get-height
datum ...))]
@defform*[((gui-racketmod+eval datum ...)
(gui-racketmod+eval
#:eval+opts the-eval get-predicate? get-render
get-get-width get-get-height
datum ...))]
@defform*[((gui-def+int datum ...)
(gui-def+int
#:eval+opts the-eval get-predicate? get-render
get-get-width get-get-height
datum ...))]
@defform*[((gui-defs+int datum ...)
(gui-defs+int
#:eval+opts the-eval get-predicate? get-render
get-get-width get-get-height
datum ...))]
)]{
The first option of each of the above is
like @racket[interaction], etc., but actually evaluating the forms
only when the @envvar{MREVAL} environment variable is set, and then in
an evaluator that is initialized with @racketmodname[racket/gui/base]
and @racketmodname[slideshow].
The second option of each allows you to specify your own evaluator via
the @racket[the-eval] argument and then to specify four thunks that
return functions for finding and rendering graphical objects:
@itemize[
@item{@racket[get-predicate? : (-> (-> any/c boolean?))]
Determines if a value is a graphical object (and thus handled by the other operations)}
@item{@racket[get-render : (-> (-> any/c (is-a?/c dc<%>) number? number? void?))]
Draws a graphical object (only called if the predicate returned @racket[#t]; the first
argument will be the value for which the predicate holds).}
@item{@racket[get-get-width : (-> (-> any/c number?))]
Gets the width of a graphical object (only called if the predicate returned @racket[#t]; the first
argument will be the value for which the predicate holds).}
@item{@racket[get-get-height : (-> (-> any/c number?))]
Gets the height of a graphical object (only called if the predicate returned @racket[#t]; the first
argument will be the value for which the predicate holds).}
]
}

3
scribble-doc/scriblib/scribblings/info.rkt
View File

@ -1,3 +0,0 @@
#lang info
(define scribblings '(("scriblib.scrbl" (multi-page) ("Scribble Libraries"))))

63
scribble-doc/scriblib/scribblings/render-cond.scrbl
View File

@ -1,63 +0,0 @@
#lang scribble/manual
@(require (for-label scribble/core
racket/base
scriblib/render-cond))
@(define scribble-doc '(lib "scribblings/scribble/scribble.scrbl"))
@title[#:tag "render-cond"]{Conditional Content}
@defmodule[scriblib/render-cond]
As much as possible, Scribble documents should be independent of the
target format for rendering the document. To customize generated
output, use styles plus ``back end'' configurations for each target
format (see @secref[#:doc scribble-doc "config"] in
@other-manual[scribble-doc]).
As a last resort, the @racket[cond-element] and @racket[cond-block]
forms support varying the document content depending on the target
format. More precisely, they generate parts of a document where
content is delayed until the @tech[#:doc scribble-doc]{traverse pass}
of document rendering. Format detection relies on the
@racket['scribble:current-render-mode] registration that is accessible
through a @racket[traverse-element] or @racket[traverse-block].
The syntax of @racket[cond-element] and @racket[cond-block] is based
on SRFI-0.
@defform*/subs[#:literals (and or not else)
[(cond-element [feature-requirement body ...+])
(cond-element [feature-requirement body ...+] [else body ...+])]
([feature-requirement identifier
(not feature-requirement)
(and feature-requirement ...)
(or feature-requirement ...)])]{
Generates a @racket[traverse-element] whose replacement content is
produced by the @racket[body] of one of the first matching
@racket[cond-element] clause.
A @racket[feature-requirement] can be any identifier; a useful
identifier is one whose symbol form can appear in a
@racket['scribble:current-render-mode] list. The identifier matches
when its symbol form is in the @racket['scribble:current-render-mode]
list. Typically, the identifier is @racket[html], @racket[latex], or
@racket[text] to indicate the corresponding rendering target.
A @racket[(not feature-requirement)] test matches when
@racket[feature-requirement] does not match, and so on. An
@racket[else] clause always matches. If no @racket[else] clause is
present and no clause matches, then the @racket[exn:fail:contract]
exception is raised. Similarly, if the result of the selected
@racket[body] is not content according to @racket[content?], then the
@racket[exn:fail:contract] exception is raised.}
@defform*[[(cond-block [feature-requirement body ...+])
(cond-block [feature-requirement body ...+] [else body ...+])]]{
Like @racket[cond-element], but generates a @racket[traverse-block]
where the selected @racket[body] must produce a block according to
@racket[block?].}

12
scribble-doc/scriblib/scribblings/scriblib.scrbl
View File

@ -1,12 +0,0 @@
#lang scribble/manual
@title{Scriblib: Extra Scribble Libraries}
@table-of-contents[]
@include-section["gui-eval.scrbl"]
@include-section["figure.scrbl"]
@include-section["autobib.scrbl"]
@include-section["bibtex.scrbl"]
@include-section["footnote.scrbl"]
@include-section["render-cond.scrbl"]

11
scribble-html-lib/LICENSE.txt
View File

@ -1,11 +0,0 @@
scribble-text-lib
Copyright (c) 2010-2014 PLT Design Inc.
This package is distributed under the GNU Lesser General Public
License (LGPL). This means that you can link this package into proprietary
applications, provided you follow the rules stated in the LGPL. You
can also modify this package; if you distribute a modified version,
you must distribute it under the terms of the LGPL, which in
particular means that you must release the source code for the
modified software. See http://www.gnu.org/copyleft/lesser.html
for more information.

11
scribble-html-lib/info.rkt
View File

@ -1,11 +0,0 @@
#lang info
(define collection 'multi)
(define deps '("scheme-lib"
"base" "at-exp-lib"
"scribble-text-lib"))
(define pkg-desc "Language for HTML with embedded Racket code")
(define pkg-authors '(mflatt eli))

4
scribble-html-lib/scribble/html.rkt
View File

@ -1,4 +0,0 @@
#lang racket/base
(require "html/main.rkt")
(provide (all-from-out "html/main.rkt"))

471
scribble-html-lib/scribble/html/html.rkt
View File

@ -1,471 +0,0 @@
#lang racket/base
;; (X)HTML elements etc.
(require "xml.rkt" scribble/text)
;; ----------------------------------------------------------------------------
;; Doctype line
(provide doctype)
(define (doctype type)
(cond [(string? type) (literal "<!DOCTYPE " type ">\n")]
[(eq? 'html type) (doctype "html")]
[(eq? 'xhtml type)
(list (literal "<?xml version=\"1.0\" encoding=\"utf-8\"?>\n")
(doctype (string-append
"html PUBLIC \"-//W3C//DTD XHTML 1.0 Strict//EN\""
" \"http://www.w3.org/TR/xhtml1/DTD/"
"xhtml1-strict.dtd\"")))]
[else (raise-type-error 'doctype
"string or known doctype symbol" type)]))
;; ----------------------------------------------------------------------------
;; Xhtml toplevel
;; creation of xhtml files requires some extra stuff
(define xhtml-prefix (doctype 'xhtml))
(provide xhtml)
(define (xhtml . body)
(list xhtml-prefix
(apply html 'xmlns: "http://www.w3.org/1999/xhtml" body)
"\n"))
;; ----------------------------------------------------------------------------
;; Elements
;; For complete reference: http://www.w3.org/TR/html/dtds.html
;; (See also http://www.w3schools.com/tags/)
;; The dtds, in increasing size:
;; http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd
;; http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd
;; http://www.w3.org/TR/xhtml1/DTD/xhtml1-frameset.dtd
;; These are all entities, taked from the DTDs. The ones marked with "[*]" are
;; defined later, since they need a different definition.
(define/provide-elements/not-empty
;; ========== Document Structure
html
;; ========== Document Head
head
;; The title element is not considered part of the flow of text.
;; It should be displayed, for example as the page header or
;; window title. Exactly one title is required per document.
title
;; base ; document base URI, can be empty [*]
;; meta ; generic metainformation, can be empty [*]
;; link ; relationship values, can be empty [*]
style ; style info, which may include CDATA sections
script ; script statements, which may include CDATA sections
noscript ; alternate content container for non script-based rendering
;; ========== Frames
frameset ; only one noframes element permitted per document
frame ; tiled window within frameset
iframe ; inline subwindow
noframes ; alternate content container for non frame-based rendering
;; ========== Document Body
body
div ; generic language/style container
;; ========== Paragraphs
p
;; ========== Headings
h1
h2
h3
h4
h5
h6
;; ========== Lists
ul ; Unordered list
ol ; Ordered (numbered) list
menu ; single column list (DEPRECATED)
dir ; multiple column list (DEPRECATED)
li ; list item
dl ; definition lists - dt for term, dd for its definition
dt
dd
;; ========== Address
address ; information on author
;; ========== Horizontal Rule
;; hr ; horizontal rule can be empty [*]
;; ========== Preformatted Text
pre
;; ========== Block-like Quotes
blockquote
;; ========== Text alignment
center ; center content
;; ========== Inserted/Deleted Text
ins
del
;; ========== The Anchor Element
a ; content is inline; except that anchors shouldn't be nested
;; ========== Inline Elements
span ; generic language/style container
bdo ; I18N BiDi over-ride
;; br ; forced line break, can be empty [*]
em ; emphasis
strong ; strong emphasis
dfn ; definitional
code ; program code
samp ; sample
kbd ; something user would type
var ; variable
cite ; citation
abbr ; abbreviation
acronym ; acronym
q ; inlined quote
sub ; subscript
sup ; superscript
tt ; fixed pitch font
i ; italic font
b ; bold font
big ; bigger font
small ; smaller font
u ; underline
s ; strike-through
strike ; strike-through
;; basefont ; base font size, can be empty [*]
font ; local change to font
;; ========== Object
object ; embeded objects
;; param ; parameters for objects, can also specify as attrs, can be empty [*]
applet ; Java applet
;; ========== Images
;; To avoid accessibility problems for people who aren't
;; able to see the image, you should provide a text
;; description using the alt and longdesc attributes.
;; In addition, avoid the use of server-side image maps.
;; img ; can be empty [*]
;; ========== Client-side image maps
;; map ; collides with scheme, but not really useful
;; area ; can be empty [*]
;; ========== Forms
form ; forms shouldn't be nested
label ; text that belongs to a form control
;; input ; form control, can be empty [*]
select ; option selector
optgroup ; option group
option ; selectable choice
textarea ; multi-line text field
fieldset ; group form fields
legend ; fieldset label (one per fieldset)
button ; push button
;; isindex ; single-line text input control (DEPRECATED), can be empty [*]
;; ========== Tables
table ; holds caption?, (col*|colgroup*), thead?, tfoot?, (tbody+|tr+)
caption ; caption text
thead ; header part, holds tr
tfoot ; footer part, holds tr
tbody ; body part, holds tr
colgroup ; column group, olds col
;; col ; column info, has only attributes, can be empty [*]
tr ; holds th or td
th ; header cell
td ; table cell
)
;; [*] empty elements, these are listed with an `EMPTY' content in
;; http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd
(define/provide-elements/empty
base meta link hr br basefont param img area input isindex col)
;; [*] elements with a cdata/comment body
(provide script/inline)
(define (script/inline . args)
(define-values [attrs body] (attributes+body args))
(make-element
'script attrs
`("\n" ,(set-prefix 0 (apply cdata #:line-prefix "//" body)) "\n")))
(provide style/inline)
(define (style/inline . args)
(define-values [attrs body] (attributes+body args))
(make-element 'style attrs `("\n" ,body "\n")))
;; ----------------------------------------------------------------------------
;; Entities
;; The three dtds that define the set of entities are at:
;; http://www.w3.org/TR/xhtml1/DTD/xhtml-lat1.ent
;; http://www.w3.org/TR/xhtml1/DTD/xhtml-special.ent
;; http://www.w3.org/TR/xhtml1/DTD/xhtml-symbol.ent
(define/provide-entities
nbsp ndash mdash bull middot sdot lsquo rsquo sbquo ldquo rdquo bdquo
lang rang dagger Dagger plusmn deg)
#; ; the complete list
(define/provide-entities
;; 24.2 Character entity references for ISO 8859-1 characters
nbsp ;00A0 no-break space = non-breaking space
iexcl ;00A1 inverted exclamation mark
cent ;00A2 cent sign
pound ;00A3 pound sign
curren ;00A4 currency sign
yen ;00A5 yen sign = yuan sign
brvbar ;00A6 broken bar = broken vertical bar
sect ;00A7 section sign
uml ;00A8 diaeresis = spacing diaeresis
copy ;00A9 copyright sign
ordf ;00AA feminine ordinal indicator
laquo ;00AB left-pointing double angle quotation mark = left pointing guillemet
not ;00AC not sign
shy ;00AD soft hyphen = discretionary hyphen
reg ;00AE registered sign = registered trade mark sign
macr ;00AF macron = spacing macron = overline = APL overbar
deg ;00B0 degree sign
plusmn ;00B1 plus-minus sign = plus-or-minus sign
sup2 ;00B2 superscript two = superscript digit two = squared
sup3 ;00B3 superscript three = superscript digit three = cubed
acute ;00B4 acute accent = spacing acute
micro ;00B5 micro sign
para ;00B6 pilcrow sign = paragraph sign
middot ;00B7 middle dot = Georgian comma = Greek middle dot
cedil ;00B8 cedilla = spacing cedilla
sup1 ;00B9 superscript one = superscript digit one
ordm ;00BA masculine ordinal indicator
raquo ;00BB right-pointing double angle quotation mark = right pointing guillemet
frac14 ;00BC vulgar fraction one quarter = fraction one quarter
frac12 ;00BD vulgar fraction one half = fraction one half
frac34 ;00BE vulgar fraction three quarters = fraction three quarters
iquest ;00BF inverted question mark = turned question mark
Agrave ;00C0 latin capital letter A with grave = latin capital letter A grave
Aacute ;00C1 latin capital letter A with acute
Acirc ;00C2 latin capital letter A with circumflex
Atilde ;00C3 latin capital letter A with tilde
Auml ;00C4 latin capital letter A with diaeresis
Aring ;00C5 latin capital letter A with ring above = latin capital letter A ring
AElig ;00C6 latin capital letter AE = latin capital ligature AE
Ccedil ;00C7 latin capital letter C with cedilla
Egrave ;00C8 latin capital letter E with grave
Eacute ;00C9 latin capital letter E with acute
Ecirc ;00CA latin capital letter E with circumflex
Euml ;00CB latin capital letter E with diaeresis
Igrave ;00CC latin capital letter I with grave
Iacute ;00CD latin capital letter I with acute
Icirc ;00CE latin capital letter I with circumflex
Iuml ;00CF latin capital letter I with diaeresis
ETH ;00D0 latin capital letter ETH
Ntilde ;00D1 latin capital letter N with tilde
Ograve ;00D2 latin capital letter O with grave
Oacute ;00D3 latin capital letter O with acute
Ocirc ;00D4 latin capital letter O with circumflex
Otilde ;00D5 latin capital letter O with tilde
Ouml ;00D6 latin capital letter O with diaeresis
times ;00D7 multiplication sign
Oslash ;00D8 latin capital letter O with stroke = latin capital letter O slash
Ugrave ;00D9 latin capital letter U with grave
Uacute ;00DA latin capital letter U with acute
Ucirc ;00DB latin capital letter U with circumflex
Uuml ;00DC latin capital letter U with diaeresis
Yacute ;00DD latin capital letter Y with acute
THORN ;00DE latin capital letter THORN
szlig ;00DF latin small letter sharp s = ess-zed
agrave ;00E0 latin small letter a with grave = latin small letter a grave
aacute ;00E1 latin small letter a with acute
acirc ;00E2 latin small letter a with circumflex
atilde ;00E3 latin small letter a with tilde
auml ;00E4 latin small letter a with diaeresis
aring ;00E5 latin small letter a with ring above = latin small letter a ring
aelig ;00E6 latin small letter ae = latin small ligature ae
ccedil ;00E7 latin small letter c with cedilla
egrave ;00E8 latin small letter e with grave
eacute ;00E9 latin small letter e with acute
ecirc ;00EA latin small letter e with circumflex
euml ;00EB latin small letter e with diaeresis
igrave ;00EC latin small letter i with grave
iacute ;00ED latin small letter i with acute
icirc ;00EE latin small letter i with circumflex
iuml ;00EF latin small letter i with diaeresis
eth ;00F0 latin small letter eth
ntilde ;00F1 latin small letter n with tilde
ograve ;00F2 latin small letter o with grave
oacute ;00F3 latin small letter o with acute
ocirc ;00F4 latin small letter o with circumflex
otilde ;00F5 latin small letter o with tilde
ouml ;00F6 latin small letter o with diaeresis
divide ;00F7 division sign
oslash ;00F8 latin small letter o with stroke, = latin small letter o slash
ugrave ;00F9 latin small letter u with grave
uacute ;00FA latin small letter u with acute
ucirc ;00FB latin small letter u with circumflex
uuml ;00FC latin small letter u with diaeresis
yacute ;00FD latin small letter y with acute
thorn ;00FE latin small letter thorn
yuml ;00FF latin small letter y with diaeresis
;; 24.3 Character entity references for symbols, mathematical symbols, and
;; Greek letters
;; Latin Extended-B
fnof ;0192 latin small f with hook = function = florin
;; Greek
Alpha ;0391 greek capital letter alpha
Beta ;0392 greek capital letter beta
Gamma ;0393 greek capital letter gamma
Delta ;0394 greek capital letter delta
Epsilon ;0395 greek capital letter epsilon
Zeta ;0396 greek capital letter zeta
Eta ;0397 greek capital letter eta
Theta ;0398 greek capital letter theta
Iota ;0399 greek capital letter iota
Kappa ;039A greek capital letter kappa
Lambda ;039B greek capital letter lambda
Mu ;039C greek capital letter mu
Nu ;039D greek capital letter nu
Xi ;039E greek capital letter xi
Omicron ;039F greek capital letter omicron
Pi ;03A0 greek capital letter pi
Rho ;03A1 greek capital letter rho
Sigma ;03A3 greek capital letter sigma
Tau ;03A4 greek capital letter tau
Upsilon ;03A5 greek capital letter upsilon
Phi ;03A6 greek capital letter phi
Chi ;03A7 greek capital letter chi
Psi ;03A8 greek capital letter psi
Omega ;03A9 greek capital letter omega
alpha ;03B1 greek small letter alpha
beta ;03B2 greek small letter beta
gamma ;03B3 greek small letter gamma
delta ;03B4 greek small letter delta
epsilon ;03B5 greek small letter epsilon
zeta ;03B6 greek small letter zeta
eta ;03B7 greek small letter eta
theta ;03B8 greek small letter theta
iota ;03B9 greek small letter iota
kappa ;03BA greek small letter kappa
lambda ;03BB greek small letter lambda
mu ;03BC greek small letter mu
nu ;03BD greek small letter nu
xi ;03BE greek small letter xi
omicron ;03BF greek small letter omicron
pi ;03C0 greek small letter pi
rho ;03C1 greek small letter rho
sigmaf ;03C2 greek small letter final sigma
sigma ;03C3 greek small letter sigma
tau ;03C4 greek small letter tau
upsilon ;03C5 greek small letter upsilon
phi ;03C6 greek small letter phi
chi ;03C7 greek small letter chi
psi ;03C8 greek small letter psi
omega ;03C9 greek small letter omega
thetasym ;03D1 greek small letter theta symbol
upsih ;03D2 greek upsilon with hook symbol
piv ;03D6 greek pi symbol
;; *** General Punctuation
bull ;2022 bullet = black small circle
hellip ;2026 horizontal ellipsis = three dot leader
prime ;2032 prime = minutes = feet
Prime ;2033 double prime = seconds = inches
oline ;203E overline = spacing overscore
frasl ;2044 fraction slash
;; *** Letterlike Symbols
weierp ;2118 script capital P = power set = Weierstrass p
image ;2111 blackletter capital I = imaginary part
real ;211C blackletter capital R = real part symbol
trade ;2122 trade mark sign
alefsym ;2135 alef symbol = first transfinite cardinal
;; *** Arrows
larr ;2190 leftwards arrow
uarr ;2191 upwards arrow
rarr ;2192 rightwards arrow
darr ;2193 downwards arrow
harr ;2194 left right arrow
crarr ;21B5 downwards arrow with corner leftwards = carriage return
lArr ;21D0 leftwards double arrow
uArr ;21D1 upwards double arrow
rArr ;21D2 rightwards double arrow
dArr ;21D3 downwards double arrow
hArr ;21D4 left right double arrow
;; Mathematical Operators
forall ;2200 for all
part ;2202 partial differential
exist ;2203 there exists
empty ;2205 empty set = null set = diameter
nabla ;2207 nabla = backward difference
isin ;2208 element of
notin ;2209 not an element of
ni ;220B contains as member
prod ;220F n-ary product = product sign
sum ;2211 n-ary sumation
minus ;2212 minus sign
lowast ;2217 asterisk operator
radic ;221A square root = radical sign
prop ;221D proportional to
infin ;221E infinity
ang ;2220 angle
and ;2227 logical and = wedge
or ;2228 logical or = vee
cap ;2229 intersection = cap
cup ;222A union = cup
int ;222B integral
there4 ;2234 therefore
sim ;223C tilde operator = varies with = similar to
cong ;2245 approximately equal to
asymp ;2248 almost equal to = asymptotic to
ne ;2260 not equal to
equiv ;2261 identical to
le ;2264 less-than or equal to
ge ;2265 greater-than or equal to
sub ;2282 subset of
sup ;2283 superset of
nsub ;2284 not a subset of
sube ;2286 subset of or equal to
supe ;2287 superset of or equal to
oplus ;2295 circled plus = direct sum
otimes ;2297 circled times = vector product
perp ;22A5 up tack = orthogonal to = perpendicular
sdot ;22C5 dot operator
;; Miscellaneous Technical
lceil ;2308 left ceiling = apl upstile
rceil ;2309 right ceiling
lfloor ;230A left floor = apl downstile
rfloor ;230B right floor
lang ;2329 left-pointing angle bracket = bra
rang ;232A right-pointing angle bracket = ket
;; Geometric Shapes
loz ;25CA lozenge
;; Miscellaneous Symbols
spades ;2660 black spade suit
clubs ;2663 black club suit = shamrock
hearts ;2665 black heart suit = valentine
diams ;2666 black diamond suit
;; 24.4 Character entity references for markup-significant and
;; internationalization characters
;; C0 Controls and Basic Latin
quot ;0022 quotation mark = APL quote
amp ;0026 ampersand
lt ;003C less-than sign
gt ;003E greater-than sign
;; Latin Extended-A
OElig ;0152 latin capital ligature OE
oelig ;0153 latin small ligature oe
Scaron ;0160 latin capital letter S with caron
scaron ;0161 latin small letter s with caron
Yuml ;0178 latin capital letter Y with diaeresis
;; Spacing Modifier Letters
circ ;02C6 modifier letter circumflex accent
tilde ;02DC small tilde
;; General Punctuation
ensp ;2002 en space
emsp ;2003 em space
thinsp ;2009 thin space
zwnj ;200C zero width non-joiner
zwj ;200D zero width joiner
lrm ;200E left-to-right mark
rlm ;200F right-to-left mark
ndash ;2013 en dash
mdash ;2014 em dash
lsquo ;2018 left single quotation mark
rsquo ;2019 right single quotation mark
sbquo ;201A single low-9 quotation mark
ldquo ;201C left double quotation mark
rdquo ;201D right double quotation mark
bdquo ;201E double low-9 quotation mark
dagger ;2020 dagger
Dagger ;2021 double dagger
permil ;2030 per mille sign
lsaquo ;2039 single left-pointing angle quotation mark
rsaquo ;203A single right-pointing angle quotation mark
euro ;20AC euro sign
)

3
scribble-html-lib/scribble/html/info.rkt
View File

@ -1,3 +0,0 @@
#lang info
(define test-responsibles '((all eli)))

14
scribble-html-lib/scribble/html/lang.rkt
View File

@ -1,14 +0,0 @@
#lang racket/base
(require "main.rkt" (except-in scribble/text/lang #%top)
scribble/text/syntax-utils)
(provide (except-out (all-from-out scribble/text/lang) #%module-begin)
(rename-out [module-begin #%module-begin])
(all-from-out "main.rkt"))
(require (for-syntax racket/base))
(define-syntax-rule (module-begin expr ...)
(#%plain-module-begin
(port-count-lines! (current-output-port))
(process-begin/text begin output-xml expr ...)))

11
scribble-html-lib/scribble/html/lang/reader.rkt
View File

@ -1,11 +0,0 @@
#lang s-exp syntax/module-reader
scribble/html/lang
#:read scribble:read-inside
#:read-syntax scribble:read-syntax-inside
#:whole-body-readers? #t
#:info (scribble-base-reader-info)
(require (prefix-in scribble: scribble/reader)
(only-in scribble/base/reader scribble-base-reader-info))

17
scribble-html-lib/scribble/html/main.rkt
View File

@ -1,17 +0,0 @@
#lang racket/base
(require "xml.rkt" "html.rkt" "resource.rkt"
;; includes all of the scribble/text utilities
scribble/text)
(provide (all-from-out "xml.rkt" "html.rkt" "resource.rkt" scribble/text)
(rename-out [top #%top]))
(require (for-syntax racket/base))
(define-syntax (top stx)
(syntax-case stx ()
[(_ . x)
(let ([x* (syntax-e #'x)])
(if (and (symbol? x*) (regexp-match? #rx":$" (symbol->string x*)))
#''x
#'(#%top . x)))]))

243
scribble-html-lib/scribble/html/resource.rkt
View File

@ -1,243 +0,0 @@
#lang racket/base
;; Resources are renderable & referrable objects, (most are html pages).
;; (resource path renderer) creates and returns a new "resource" value. The
;; arguments are:
;; - `path': the path of the output file, relative to the working directory,
;; indicating where the resource file should be put at, also corresponding to
;; the URL it will be found at. It must be a `/'-separated relative string,
;; no `..', `.', or `//', and it can end in `/' (which will turn to
;; "index.html").
;; - `renderer': a unary function that renders the resource, receiving the path
;; for the file to be created as an argument. This path will be different
;; than the `path' argument because this function is invoked in the target
;; directory.
;; The resulting resource value is a function that returns the URL for the
;; resource. The function takes in an optional boolean which defaults to #f,
;; and when #t is given, the result will be an absolute full URL. Note that
;; the function can be used as a value for output, which will use it as a thunk
;; (that renders as the relative URL for the resource). The default relative
;; resulting URL is, of course, a value that depends on the currently rendered
;; resource that uses this value. Creating a resource registers the `renderer'
;; to be executed when rendering is initiated by `render-all'. Note that more
;; resources can be created while rendering; they will also be rendered in turn
;; until no more new resources are created.
(require scribble/text)
;; default file, urls to it will point to its directory instead, a
;; /-suffixed path will render to this file, and `url-roots' entries
;; with 'index will append this file name to a rewritten path that
;; otherwise ends in /
(define default-file "index.html")
;; the currently rendered directory, as a list
(define rendered-dirpath (make-parameter '()))
;; A mapping from path prefixes to urls (actually, any string) -- when two
;; paths are in the same prefix, links from one to the other are relative
;; (unless absolute links are requested) , but if they're in different
;; prefixes, the url will be used instead; the roots are expected to be
;; disjoint (= no "/foo" and "/foo/bar" roots). Additionally, optional symbol
;; flags can appear in each entry, currently only 'abs is used below for roots
;; that should always use absolute links (needed for some skeleton pages that
;; are used in nested subdirectories).
(provide url-roots)
(define url-roots (make-parameter #f))
(define cached-roots '(#f . #f))
(define (current-url-roots)
;; takes `url-roots', a (listof (list prefix-string url-string . flags)), and
;; produces an alist with lists of strings for the keys; the prefix-strings
;; are split on "/"s, and the url-strings can be anything at all actually
;; (they are put as-is before the path with a "/" between them).
(define roots (url-roots))
(unless (eq? roots (car cached-roots))
(set! cached-roots
(cons roots
(and (list? roots) (pair? roots)
(map (lambda (root)
(list* (regexp-match* #rx"[^/]+" (car root))
(regexp-replace #rx"/$" (cadr root) "")
(cddr root)))
roots)))))
(cdr cached-roots))
;; a utility for relative paths, taking the above `default-file' and
;; `url-roots' into consideration.
(define (relativize file tgtdir curdir)
(define file* (if (equal? file default-file) "" file))
(define roots (current-url-roots))
(define (find-root path mode)
(ormap (lambda (root+url+flags)
(let loop ([r (car root+url+flags)] [p path])
(if (pair? r)
(and (pair? p) (equal? (car p) (car r))
(loop (cdr r) (cdr p)))
(case mode
[(get-path) `(,(cadr root+url+flags)
,@p
,(if (and (equal? file* "")
(memq 'index (cddr root+url+flags)))
default-file
file*))]
[(get-abs-or-true)
(if (memq 'abs (cddr root+url+flags)) `("" ,@p) #t)]
[else (error 'relativize "internal error: ~e" mode)]))))
roots))
(define result
(let loop ([t tgtdir] [c curdir] [pfx '()])
(cond
;; find shared prefix
[(and (pair? t) (pair? c) (equal? (car t) (car c)))
(loop (cdr t) (cdr c) (cons (car t) pfx))]
;; done with the shared prefix, deal with the root now
;; no roots => always use a relative path (useful for debugging)
[(not roots) `(,@(map (lambda (_) "..") c) ,@t ,file*)]
;; share a root => use a relative path unless its an absolute root
[(find-root (reverse pfx) 'get-abs-or-true)
=> (lambda (abs/true)
`(;; rel. => as above
,@(if (list? abs/true) abs/true (map (lambda (_) "..") c))
,@t ,file*))]
;; different roots => use the one for the target
[(find-root tgtdir 'get-path)]
;; if there isn't any, throw an error
[else (error 'relativize "target url is not in any known root: ~a"
(string-join `(,@tgtdir ,file*) "/"))])))
(if (equal? '("") result) "." (string-join result "/")))
#;
(module+ test
(require tests/eli-tester)
(define R relativize)
(let ()
(test do (test (R "bleh.txt" '() '() ) => "bleh.txt"
(R "bleh.txt" '("x") '() ) => "x/bleh.txt"
(R "bleh.txt" '("x" "y") '() ) => "x/y/bleh.txt"
(R "bleh.txt" '() '("x") ) => "../bleh.txt"
(R "bleh.txt" '("x") '("x") ) => "bleh.txt"
(R "bleh.txt" '("x" "y") '("x") ) => "y/bleh.txt"
(R "bleh.txt" '() '("x" "y")) => "../../bleh.txt"
(R "bleh.txt" '("x") '("x" "y")) => "../bleh.txt"
(R "bleh.txt" '("x" "y") '("x" "y")) => "bleh.txt"
(R "bleh.txt" '("x" "y") '("y" "x")) => "../../x/y/bleh.txt"
(R "index.html" '() '() ) => "."
(R "index.html" '("x") '() ) => "x/"
(R "index.html" '("x" "y") '() ) => "x/y/"
(R "index.html" '() '("x") ) => "../"
(R "index.html" '("x") '("x") ) => "."
(R "index.html" '("x" "y") '("x") ) => "y/"
(R "index.html" '() '("x" "y")) => "../../"
(R "index.html" '("x") '("x" "y")) => "../"
(R "index.html" '("x" "y") '("x" "y")) => "."
(R "index.html" '("x" "y") '("y" "x")) => "../../x/y/")
do (parameterize ([url-roots '(["/x" "/X/"] ["/y" "/Y/"])])
(test (R "bleh.txt" '() '() ) =error> "not in any"
(R "bleh.txt" '("x") '() ) => "/X/bleh.txt"
(R "bleh.txt" '("x" "y") '() ) => "/X/y/bleh.txt"
(R "bleh.txt" '() '("x") ) =error> "not in any"
(R "bleh.txt" '("x") '("x") ) => "bleh.txt"
(R "bleh.txt" '("x" "y") '("x") ) => "y/bleh.txt"
(R "bleh.txt" '() '("x" "y")) =error> "not in any"
(R "bleh.txt" '("x") '("x" "y")) => "../bleh.txt"
(R "bleh.txt" '("x" "y") '("x" "y")) => "bleh.txt"
(R "bleh.txt" '("x" "y") '("y" "x")) => "/X/y/bleh.txt"
(R "index.html" '() '() ) =error> "not in any"
(R "index.html" '("x") '() ) => "/X/"
(R "index.html" '("x" "y") '() ) => "/X/y/"
(R "index.html" '() '("x") ) =error> "not in any"
(R "index.html" '("x") '("x") ) => "."
(R "index.html" '("x" "y") '("x") ) => "y/"
(R "index.html" '() '("x" "y")) =error> "not in any"
(R "index.html" '("x") '("x" "y")) => "../"
(R "index.html" '("x" "y") '("x" "y")) => "."
(R "index.html" '("x" "y") '("y" "x")) => "/X/y/"))
do (parameterize ([url-roots '(["/x" "/X/"] ["/y" "/Y/" abs])])
(test (R "foo.txt" '("x" "1") '("x" "2")) => "../1/foo.txt"
(R "foo.txt" '("y" "1") '("y" "2")) => "/1/foo.txt")))))
;; utility for keeping a list of renderer thunks
(define-values [add-renderer get/reset-renderers]
(let ([l '()] [s (make-semaphore 1)])
;; map paths to #t -- used to avoid overwriting files
(define t (make-hash))
(define-syntax-rule (S body) (call-with-semaphore s (lambda () body)))
(values (lambda (path renderer)
(S (if (hash-ref t path #f)
(error 'resource "path used for two resources: ~e" path)
(begin (hash-set! t path #t) (set! l (cons renderer l))))))
(lambda () (S (begin0 (reverse l) (set! l '())))))))
;; `#:exists' determines what happens when the render destination exists, it
;; can be one of: #f (do nothing), 'delete-file (delete if a file exists, error
;; if exists as a directory)
(provide resource resource?)
;; use a struct to make resources identifiable as such
(struct resource (url) #:constructor-name make-resource
#:property prop:procedure 0 #:omit-define-syntaxes)
(define (resource path0 renderer #:exists [exists 'delete-file])
(define (bad reason) (error 'resource "bad path, ~a: ~e" reason path0))
(unless (string? path0) (bad "must be a string"))
(for ([x (in-list '([#rx"^/" "must be relative"]
[#rx"//" "must not have empty elements"]
[#rx"(?:^|/)[.][.]?(?:/|$)"
"must not contain `.' or `..'"]))])
(when (regexp-match? (car x) path0) (bad (cadr x))))
(define path (regexp-replace #rx"(?<=^|/)$" path0 default-file))
(define-values [dirpathlist filename]
(let-values ([(l r) (split-at-right (regexp-split #rx"/" path) 1)])
(values l (car r))))
(define (render)
(let loop ([ps dirpathlist])
(if (pair? ps)
(begin (unless (directory-exists? (car ps))
(if (or (file-exists? (car ps)) (link-exists? (car ps)))
(bad "exists as a file/link")
(make-directory (car ps))))
(parameterize ([current-directory (car ps)])
(loop (cdr ps))))
(begin (cond [(not exists)] ; do nothing
[(or (file-exists? filename) (link-exists? filename))
(delete-file filename)]
[(directory-exists? filename)
(bad "exists as directory")])
(parameterize ([rendered-dirpath dirpathlist])
(printf " ~a\n" path)
(renderer filename))))))
(define absolute-url
(lazy (define url (relativize filename dirpathlist '()))
(if (url-roots)
url
;; we're in local build mode, and insist on an absolute url, so
;; construct a `file://' result
(list* "file://" (current-directory) url))))
(when renderer
(add-renderer path render))
(define (url [absolute? #f])
;; be conservative, in case it needs to be extended in the future
(case absolute?
[(#f) (relativize filename dirpathlist (rendered-dirpath))]
[(#t) (force absolute-url)]
[else (error 'resource "bad absolute flag value: ~e" absolute?)]))
(make-resource url))
;; a convenient utility to create renderers from some output function (like
;; `output-xml' or `display') and some content
(provide file-writer)
(define ((file-writer writer content) file)
(call-with-output-file file (lambda (o) (writer content o))))
;; runs all renderers, and any renderers that might have been added on the way
(provide render-all)
(define (render-all)
(printf "Rendering...\n")
(define todo (get/reset-renderers))
(if (null? todo)
(printf " Warning: no content to render\n")
(let loop ([todo todo])
(unless (null? todo)
(for-each (lambda (r) (r)) todo)
(loop (get/reset-renderers))))) ; if more were created
(printf "Rendering done.\n"))

162
scribble-html-lib/scribble/html/xml.rkt
View File

@ -1,162 +0,0 @@
#lang racket/base
;; XML-like objects and functions, with rendering
(require scribble/text racket/port)
;; ----------------------------------------------------------------------------
;; Represent attribute names as `foo:' symbols. They are made self-quoting in
;; the language. A different option would be to use the usual racket keyword
;; arguments, but that tends to have problems like disallowing repeated uses of
;; the same keyword, sorting the keywords alphabetically, and ambiguity when
;; some keywords are meant to do the usual thing (customize a function) instead
;; of representing an attribute. It's more convenient to just have a separate
;; mechanism for this, so racket keywords are still used in the same way, and
;; orthogonal to specifying attributes. Another possibility is to have a new
;; type, with `foo:' evaluating to instances -- but it's often convenient to
;; pass them around as quoted lists.
(define attribute->symbol
(let ([t (make-weak-hasheq)])
(lambda (x)
(and (symbol? x)
(hash-ref! t x
(lambda ()
(define m (regexp-match #rx"^(.*):$" (symbol->string x)))
(and m (string->symbol (cadr m)))))))))
(provide attribute?)
(define attribute? attribute->symbol)
(provide attributes+body)
(define (attributes+body xs)
(let loop ([xs xs] [as '()])
(define a (and (pair? xs) (attribute->symbol (car xs))))
(cond [(not a) (values (reverse as) xs)]
[(null? (cdr xs)) (error 'attriubtes+body
"missing attribute value for `~s:'" a)]
[else (loop (cddr xs) (cons (cons a (cadr xs)) as))])))
;; similar, but keeps the attributes as a list, useful to build new functions
;; that accept attributes without knowing about the xml structs.
(provide split-attributes+body)
(define (split-attributes+body xs)
(let loop ([xs xs] [as '()])
(if (and (pair? xs) (pair? (cdr xs)) (attribute->symbol (car xs)))
(loop (cddr xs) (list* (cadr xs) (car xs) as))
(values (reverse as) xs))))
;; ----------------------------------------------------------------------------
;; An output that handles xml quoting, customizable
;; TODO: make this more conveniently customizable and extensible
(define (write-string/xml-quote str p [start 0] [end (string-length str)])
(let loop ([start start])
(when (< start end)
(define m (regexp-match-positions #rx"[&<>\"]" str start end p))
(when m
(write-string (case (string-ref str (caar m))
[(#\&) "&amp;"]
[(#\<) "&lt;"]
[(#\>) "&gt;"]
[(#\") "&quot;"])
p)
(loop (cdar m))))))
(provide xml-writer)
(define xml-writer (make-parameter write-string/xml-quote))
(provide output-xml)
(define (output-xml content [p (current-output-port)])
(output (disable-prefix (with-writer (xml-writer) content)) p))
(provide xml->string)
(define (xml->string content)
(with-output-to-string (lambda () (output-xml content))))
;; ----------------------------------------------------------------------------
;; Structs for xml data: elements, literals, entities
(provide make-element)
(struct element (tag attrs body [cache #:auto #:mutable])
#:constructor-name make-element
#:transparent #:omit-define-syntaxes #:auto-value #f
#:property prop:procedure
(lambda (e)
(unless (element-cache e) (set-element-cache! e (element->output e)))
(element-cache e)))
(provide element)
(define (element tag . args)
(define-values [attrs body] (attributes+body args))
(make-element tag attrs body))
;; similar to element, but will always have a closing tag instead of using the
;; short syntax (see also `element->output' below)
(provide element/not-empty)
(define (element/not-empty tag . args)
(define-values [attrs body] (attributes+body args))
(make-element tag attrs (if (null? body) '(#f) body)))
;; convert an element to something output-able
(define (element->output e)
(define tag (element-tag e))
(define attrs (element-attrs e))
(define body (element-body e))
;; null body means a lone tag, tags that should always have a closer will
;; have a '(#f) as their body (see below)
(list (with-writer #f "<" tag)
(map (lambda (attr)
(define name (car attr))
(define val (cdr attr))
(cond [(not val) #f]
;; #t means just mention the attribute
[(eq? #t val) (with-writer #f (list " " name))]
[else (list (with-writer #f (list " " name "=\""))
val
(with-writer #f "\""))]))
attrs)
(if (null? body)
(with-writer #f " />")
(list (with-writer #f ">")
body
(with-writer #f "</" tag ">")))))
;; ----------------------------------------------------------------------------
;; Literals
;; literal "struct" for things that are not escaped
(provide literal)
(define (literal . contents) (with-writer #f contents))
;; entities are implemented as literals
(provide entity)
(define (entity x) (literal "&" (and (number? x) "#") x ";"))
;; comments and cdata
(provide comment)
(define (comment #:newlines? [newlines? #f] . body)
(define newline (and newlines? "\n"))
(literal "<!--" newline body newline "-->"))
(provide cdata)
(define (cdata #:newlines? [newlines? #t] #:line-prefix [pfx #f] . body)
(define newline (and newlines? "\n"))
(literal pfx "<![CDATA[" newline body newline pfx "]]>"))
;; ----------------------------------------------------------------------------
;; Template definition forms
(provide define/provide-elements/empty
define/provide-elements/not-empty
define/provide-entities)
(define-syntax-rule (define/provide-elements/empty tag ...)
(begin (provide tag ...)
(define (tag . args) (apply element 'tag args)) ...))
(define-syntax-rule (define/provide-elements/not-empty tag ...)
(begin (provide tag ...)
(define (tag . args) (apply element/not-empty 'tag args)) ...))
(define-syntax-rule (define/provide-entities ent ...)
(begin (provide ent ...)
(define ent ; use string-append to make it a little faster
(literal (string-append "&" (symbol->string 'ent) ";")))
...))

11
scribble-lib/LICENSE.txt
View File

@ -1,11 +0,0 @@
scribble-lib
Copyright (c) 2010-2014 PLT Design Inc.
This package is distributed under the GNU Lesser General Public
License (LGPL). This means that you can link this package into proprietary
applications, provided you follow the rules stated in the LGPL. You
can also modify this package; if you distribute a modified version,
you must distribute it under the terms of the LGPL, which in
particular means that you must release the source code for the
modified software. See http://www.gnu.org/copyleft/lesser.html
for more information.

21
scribble-lib/help/help.rkt
View File

@ -1,21 +0,0 @@
#lang scheme/base
(require "search.rkt" scheme/cmdline scheme/list scheme/string
raco/command-name)
;; Minimal command-line arguments, the query string can contain all
;; kinds of magic.
(command-line
#:program (short-program+command-name)
#:handlers
(lambda (_ . ts)
(if (null? ts)
(send-main-page)
(perform-search (string-append* (add-between ts " ")))))
'("search-terms")
(lambda (help-str)
(display help-str)
(display " See the search page for the syntax of queries\n")
(exit 0)))
(module test racket/base)

3
scribble-lib/help/info.rkt
View File

@ -1,3 +0,0 @@
#lang info
(define compile-omit-files '("tests"))

81
scribble-lib/help/search.rkt
View File

@ -1,81 +0,0 @@
#lang racket/base
(require setup/dirs
net/sendurl
net/uri-codec
net/url
racket/string)
(provide perform-search send-main-page)
(define search-dir "search/")
;; Almost nothing to do here -- the real work is done in the browser,
;; using javascript.
(define (send-main-page #:sub [sub "index.html"]
#:fragment [fragment #f] #:query [query #f]
#:notify [notify void])
(define open-url (get-doc-open-url))
(cond
[open-url
(define dest-url (let ([u (string->url open-url)])
(combine-url/relative
u
(string-join
(for/list ([s (explode-path sub)])
(if (path? s)
(path-element->string s)
(format "~a" s)))
"/"))))
(notify (url->string dest-url))
(send-url (url->string
(struct-copy url dest-url
[fragment (or fragment
(url-fragment dest-url))]
[query (append
(url-query dest-url)
(if query
(url-query
(string->url
(format "q?~a" query)))
null))])))]
[else
(let* ([path (build-path (find-user-doc-dir) sub)]
[path (if (file-exists? path) path (build-path (find-doc-dir) sub))])
(notify path)
(send-url/file path #:fragment fragment #:query query))]))
;; This is an example of changing this code to use the online manuals.
;; Normally, it's better to set `doc-open-url` in "etc/config.rktd",
;; but as a last resort, you can change `send-main-page` to compute a URL.
;; This may be useful in cases like schools that use systems that have problems
;; running a browser on local files (like NEU). If you use this, then
;; it is a good idea to put the documentation tree somewhere local, to
;; have better interaction times instead of using the PLT server.
;; (define (send-main-page #:sub [sub "index.html"]
;; #:fragment [fragment #f] #:query [query #f]
;; #:notify [notify void])
;; (define (part pfx x) (if x (string-append pfx x) ""))
;; (send-url (string-append
;; "http://download.racket-lang.org/docs/" (version) "/html/"
;; sub (part "#" fragment) (part "?" query))))
(define (perform-search str [context #f])
;; `context' can be a pre-filter query string to use for a context,
;; optionally a list of one and a label to display for that context.
;; In any case, when a context is specified, the search actually
;; goes through the search-context.html page which tranpolines to
;; the main search page after setting the cookies (so when the
;; search page is refreshed it won't reset the context).
(let* ([label (and (list? context) (= 2 (length context)) (cadr context))]
[context (if (pair? context) (car context) context)]
[page (if context "search-context.html" "index.html")]
[query (format "q=~a" (uri-encode str))]
[query (if context
(format "~a&hq=~a~a"
query (uri-encode context)
(if label
(format "&label=~a" (uri-encode label))
""))
query)])
(send-main-page #:sub (string-append search-dir page) #:query query)))

26
scribble-lib/info.rkt
View File

@ -1,26 +0,0 @@
#lang info
(define collection 'multi)
(define deps '("scheme-lib"
"base"
"compatibility-lib"
"scribble-text-lib"
"scribble-html-lib"
"planet-lib" ; used dynamically
"net-lib"
"at-exp-lib"
"draw-lib"
"syntax-color-lib"
"sandbox-lib"
"typed-racket-lib"
))
(define build-deps '("rackunit-lib"))
(define implies '("scribble-html-lib"))
(define pkg-desc "implementation (no documentation) part of \"scribble\"")
(define pkg-authors '(mflatt eli))
(define version "1.17")

26
scribble-lib/scribble/HISTORY.txt
View File

@ -1,26 +0,0 @@
Version 1.1
Moved detailed-change recording to documentation
Version 1.0
Use `doc' submodule when available
Changed the HTML rendering style of `scribble/manual'
Changed `verbatim' to support non-string arguments
Added `--html-tree' option to for rendering to multi-page HTML
with nested directories for nested parts
Added `css-style-addition' and `js-style-addition' for adding
style files that override library-level defaults but can be
overridden externally
For HTML rendering, merge generated `style' attributes within
a single tag
scribble/base: same change as for racket/runtime-path related
to "collects"-relative paths
scribble/base: added `#:indirect' option to `defmodule` and
`seclink`
scribble/manual: added `manual-doc-style'
scribble/manual: changed `deprecated' to a function, and
generalized it by adding an optional `#:what' argument
scriblib/autobib: add #:note
Older versions
See the "Racket core" release notes for a history of changes before
the "scribble-lib" package was created.

1152
scribble-lib/scribble/base-render.rkt
View File

File diff suppressed because it is too large Load Diff

976
scribble-lib/scribble/base.rkt
View File

@ -1,976 +0,0 @@
#lang scheme/base
(require "decode.rkt"
"core.rkt"
"manual-struct.rkt"
"decode-struct.rkt"
"html-properties.rkt"
"tag.rkt"
scheme/list
scheme/class
racket/contract/base
racket/contract/combinator
(for-syntax scheme/base))
(provide (all-from-out "tag.rkt"))
;; ----------------------------------------
(define-syntax-rule (title-like-contract)
(->* ()
(#:tag (or/c #f string? (listof string?))
#:tag-prefix (or/c #f string? module-path?)
#:style (or/c style? string? symbol? (listof symbol?) #f))
#:rest (listof pre-content?)
part-start?))
(provide/contract
[title (->* ()
(#:tag (or/c #f string? (listof string?))
#:tag-prefix (or/c #f string? module-path?)
#:style (or/c style? string? symbol? (listof symbol?) #f)
#:version (or/c string? #f)
#:date (or/c string? #f))
#:rest (listof pre-content?)
title-decl?)]
[section (title-like-contract)]
[subsection (title-like-contract)]
[subsubsection (title-like-contract)]
[subsubsub*section (->* ()
(#:tag (or/c #f string? (listof string?)))
#:rest (listof pre-content?)
block?)])
(provide include-section)
(define (gen-tag content)
(datum-intern-literal
(regexp-replace* "[^-a-zA-Z0-9_=]" (content->string content) "_")))
(define (prefix->string p)
(and p (if (string? p)
(datum-intern-literal p)
(module-path-prefix->string p))))
(define (convert-tag tag content)
(if (list? tag)
(append-map (lambda (t) (convert-tag t content)) tag)
`((part ,(or tag (gen-tag content))))))
(define (convert-part-style who s)
(cond
[(style? s) s]
[(not s) plain]
[(string? s) (make-style s null)]
[(symbol? s) (make-style #f (list s))]
[(and (list? s) (andmap symbol? s)) (make-style #f s)]
[else (raise-argument-error who "(or/c style? string? symbol? (listof symbol?) #f)" s)]))
(define (title #:tag [tag #f] #:tag-prefix [prefix #f] #:style [style plain]
#:version [version #f] #:date [date #f]
. str)
(let ([content (decode-content str)])
(make-title-decl (prefix->string prefix)
(convert-tag tag content)
version
(let ([s (convert-part-style 'title style)])
(if date
(make-style (style-name s)
(cons (make-document-date date)
(style-properties s)))
s))
content)))
(define (section #:tag [tag #f] #:tag-prefix [prefix #f] #:style [style plain]
. str)
(let ([content (decode-content str)])
(make-part-start 0 (prefix->string prefix)
(convert-tag tag content)
(convert-part-style 'section style)
content)))
(define (subsection #:tag [tag #f] #:tag-prefix [prefix #f] #:style [style plain]
. str)
(let ([content (decode-content str)])
(make-part-start 1
(prefix->string prefix)
(convert-tag tag content)
(convert-part-style 'subsection style)
content)))
(define (subsubsection #:tag [tag #f] #:tag-prefix [prefix #f]
#:style [style plain] . str)
(let ([content (decode-content str)])
(make-part-start 2
(prefix->string prefix)
(convert-tag tag content)
(convert-part-style 'subsubsection style)
content)))
(define (subsubsub*section #:tag [tag #f] . str)
(let ([content (decode-content str)])
(make-paragraph plain
(list
(make-element "SSubSubSubSection"
(if tag
(make-target-element #f content `(part ,tag))
content))))))
(define-syntax (include-section stx)
(syntax-case stx ()
[(_ mod)
(with-syntax ([doc-from-mod (datum->syntax #'mod 'doc)])
(unless (module-path? (syntax->datum #'mod))
(raise-syntax-error #f
"not a module path"
stx
#'mod))
#'(begin
(require (only-in mod [doc-from-mod doc]))
doc))]))
;; ----------------------------------------
(provide/contract
[author (->* (content?) () #:rest (listof content?) block?)]
[author+email (->* (content? string?) (#:obfuscate? any/c) element?)])
(define (author . auths)
(make-paragraph
(make-style 'author null)
(let ([nl (make-element 'newline '("\n"))])
(case (length auths)
[(1) auths]
[(2) (list (car auths) nl "and " (cadr auths))]
[else (let ([r (reverse auths)])
(append (add-between (reverse (cdr r))
(make-element #f (list "," nl)))
(list "," nl "and " (car r))))]))))
(define (author+email name email #:obfuscate? [obfuscate? #f])
(make-element #f
(list
name
" <"
(if obfuscate?
(regexp-replace* #rx"[.]"
(regexp-replace* #rx"@" email " at ")
" dot ")
(hyperlink (string-append "mailto:" email) email))
">")))
;; ----------------------------------------
(define (item? x) (an-item? x))
(define recur-items/c
(make-flat-contract
#:name 'items/c
#:first-order (lambda (x)
((flat-contract-predicate items/c) x))))
(define items/c (or/c item?
block?
(listof recur-items/c)
(spliceof recur-items/c)))
(provide items/c)
(provide/contract
[itemlist (->* ()
(#:style (or/c style? string? symbol? #f))
#:rest (listof items/c)
itemization?)]
[item (->* ()
()
#:rest (listof pre-flow?)
item?)])
(provide/contract
[item? (any/c . -> . boolean?)])
(define (itemlist #:style [style plain] . items)
(let ([flows (let loop ([items items])
(cond
[(null? items) null]
[(item? (car items)) (cons (an-item-flow (car items))
(loop (cdr items)))]
[(block? (car items)) (cons (list (car items))
(loop (cdr items)))]
[(splice? (car items))
(loop (append (splice-run (car items))
(cdr items)))]
[else
(loop (append (car items) (cdr items)))]))])
(make-itemization (convert-block-style style) flows)))
(define-struct an-item (flow))
(define (item . str)
(make-an-item (decode-flow str)))
;; ----------------------------------------
(provide ._ .__ ~ ?- -~-)
(define ._ (make-element (make-style "Sendabbrev" null) "."))
(define .__ (make-element (make-style "Sendsentence" null) "."))
(define ~ "\uA0")
(define ?- "\uAD")
(define -~- "\u2011")
;; ----------------------------------------
(define elem-like-contract
(->* () () #:rest (listof pre-content?) element?))
(provide/contract
[linebreak (-> element?)]
[nonbreaking elem-like-contract]
[hspace (-> exact-nonnegative-integer? element?)]
[elem (->* ()
(#:style element-style?)
#:rest (listof pre-content?)
element?)]
[italic elem-like-contract]
[bold elem-like-contract]
[smaller elem-like-contract]
[larger elem-like-contract]
[emph elem-like-contract]
[tt elem-like-contract]
[subscript elem-like-contract]
[superscript elem-like-contract]
[literal (->* (string?) () #:rest (listof string?) element?)]
[image (->* ((or/c path-string? (cons/c 'collects (listof bytes?))))
(#:scale real?
#:suffixes (listof (and/c string? #rx"^[.]"))
#:style element-style?)
#:rest (listof content?)
image-element?)])
(define hspace-cache (make-vector 100 #f))
(define (hspace n)
(if (n . < . (vector-length hspace-cache))
(or (vector-ref hspace-cache n)
(let ([h (make-element 'hspace (list (make-string n #\space)))])
(vector-set! hspace-cache n h)
h))
(make-element 'hspace (list (make-string n #\space)))))
(define (linebreak)
(make-element 'newline '("\n")))
(define (nonbreaking . str)
(make-element 'no-break (decode-content str)))
(define (elem #:style [style plain] . str)
(make-element style (decode-content str)))
(define (italic . str)
(make-element 'italic (decode-content str)))
(define (bold . str)
(make-element 'bold (decode-content str)))
(define (smaller . str)
(make-element 'smaller (decode-content str)))
(define (larger . str)
(make-element 'larger (decode-content str)))
(define (emph . str)
(make-element 'italic (decode-content str)))
(define (tt . str)
(let* ([l (decode-content str)]
[l (let ([m (and (pair? l)
(string? (car l))
(regexp-match-positions #rx"^ +" (car l)))])
(if m
(list* (hspace (- (cdar m) (caar m)))
(substring (car l) (cdar m))
(cdr l))
l))])
(if (andmap string? l)
(make-element 'tt l)
(make-element #f (map (lambda (s)
(if (or (string? s) (symbol? s))
(make-element 'tt (list s))
s))
l)))))
(define (span-class classname . str)
(make-element classname (decode-content str)))
(define (subscript . str)
(make-element 'subscript (decode-content str)))
(define (superscript . str)
(make-element 'superscript (decode-content str)))
(define (literal s . strs)
(let ([s (apply string-append s strs)])
(make-element #f s)))
(define (image #:scale [scale 1.0]
filename-relative-to-source
#:suffixes [suffixes null]
#:style [style #f]
. alt)
(make-image-element style
(decode-content alt)
filename-relative-to-source
suffixes
scale))
;; ----------------------------------------
(define (cell-spec/c c)
(define rc
(recursive-contract (or/c c
empty
(cons/c rc rc))))
rc)
(provide/contract
[para (->* ()
(#:style (or/c style? string? symbol? #f ))
#:rest (listof pre-content?)
paragraph?)]
[nested (->* ()
(#:style (or/c style? string? symbol? #f ))
#:rest (listof pre-flow?)
nested-flow?)]
[compound (->* ()
(#:style (or/c style? string? symbol? #f ))
#:rest (listof pre-flow?)
compound-paragraph?)]
[tabular (->* ((listof (listof (or/c 'cont block? content?))))
(#:style (or/c style? string? symbol? #f)
#:sep (or/c content? block? #f)
#:column-properties (listof any/c)
#:row-properties (listof any/c)
#:cell-properties (listof (listof any/c)))
table?)])
(define (convert-block-style style)
(cond
[(style? style) style]
[(or (string? style) (symbol? style)) (make-style style null)]
[else plain]))
(define (nested #:style [style #f] . c)
(make-nested-flow (convert-block-style style)
(decode-flow c)))
(define (para #:style [style #f] . c)
(make-paragraph (convert-block-style style)
(decode-content c)))
(define (compound #:style [style #f] . c)
(make-compound-paragraph (convert-block-style style)
(decode-flow c)))
(define (tabular #:style [style #f]
#:sep [sep #f]
#:column-properties [column-properties null]
#:row-properties [row-properties null]
#:cell-properties [cell-properties null]
cells)
(define (nth-str pos)
(case (modulo pos 10)
[(1) "st"]
[(2) "nd"]
[(3) "rd"]
[else "th"]))
(unless (null? cells)
(let ([n (length (car cells))])
(for ([row (in-list (cdr cells))]
[pos (in-naturals 2)])
(unless (= n (length row))
(raise-mismatch-error
'tabular
(format "bad length (~a does not match first row's length ~a) for ~a~a row: "
(length row)
n
pos
(nth-str pos))
row)))))
(for ([row (in-list cells)]
[pos (in-naturals 1)])
(when (and (pair? row) (eq? (car row) 'cont))
(raise-mismatch-error
'tabular
(format "~a~a row starts with 'cont: " pos (nth-str pos))
row)))
(make-table (let ([s (convert-block-style style)])
(define n-orig-cols (if (null? cells)
0
(length (car cells))))
(define n-cols (if sep
(max 0 (sub1 (* n-orig-cols 2)))
n-orig-cols))
(define n-rows (length cells))
(unless (null? cells)
(when ((length column-properties) . > . n-orig-cols)
(raise-mismatch-error
'tabular
"column properties list is too long: "
column-properties)))
(when ((length row-properties) . > . n-rows)
(raise-mismatch-error
'tabular
"row properties list is too long: "
row-properties))
(when ((length cell-properties) . > . n-rows)
(raise-mismatch-error
'tabular
"cell properties list is too long: "
cell-properties))
(unless (null? cells)
(for ([row (in-list cell-properties)])
(when ((length row) . > . n-orig-cols)
(raise-mismatch-error
'tabular
"row list within cell properties list is too long: "
row))))
;; Expand given column and cell properties lists to match
;; the dimensions of the given `cells` by duplicating
;; the last element of a list as needed (and ignoring
;; extra elements):
(define (make-full-column-properties column-properties)
(let loop ([column-properties column-properties]
[n 0]
[prev null])
(cond
[(= n n-cols) null]
[(null? column-properties)
(if (or (zero? n) (not sep))
(cons prev (loop null (add1 n) prev))
(list* prev prev (loop null (+ n 2) prev)))]
[else
(define (to-list v) (if (list? v) v (list v)))
(define props (to-list (car column-properties)))
(define rest (loop (cdr column-properties)
(if (or (zero? n) (not sep))
(add1 n)
(+ n 2))
props))
(if (or (zero? n) (not sep))
(cons props rest)
(list* null props rest))])))
(define full-column-properties
(make-full-column-properties column-properties))
(define (make-full-cell-properties cell-properties)
(let loop ([cell-properties cell-properties]
[n 0]
[prev (make-list n-cols null)])
(cond
[(= n n-rows) null]
[(null? cell-properties)
(cons prev (loop null (add1 n) prev))]
[else
(define props (make-full-column-properties (car cell-properties)))
(cons props
(loop (cdr cell-properties)
(add1 n)
props))])))
(define full-cell-properties
(for/list ([c-row (in-list (make-full-cell-properties cell-properties))]
[r-row (in-list (make-full-cell-properties (map list row-properties)))])
(for/list ([c (in-list c-row)]
[r (in-list r-row)])
(append c r))))
(define all-cell-properties
(and (or (pair? row-properties)
(pair? cell-properties))
(if (null? column-properties)
full-cell-properties
(for/list ([row (in-list full-cell-properties)])
(for/list ([cell (in-list row)]
[col (in-list full-column-properties)])
(append cell col))))))
(define all-column-properties
(and (pair? column-properties)
full-column-properties))
;; Will werge `cell-properties` and `column-properties` into
;; `s`. Start by finding any existing `table-columns`
;; and `table-cells` properties with the right number of
;; styles:
(define props (style-properties s))
(define tc (and all-column-properties
(let ([tc (ormap (lambda (v) (and (table-columns? v) v))
props)])
(if (and tc
(= (length (table-columns-styles tc))
n-cols))
tc
#f))))
(define tl (and all-cell-properties
(let ([tl (ormap (lambda (v) (and (table-cells? v) v))
props)])
(if (and tl
(= (length (table-cells-styless tl))
n-rows)
(andmap (lambda (cl)
(= (length cl) n-cols))
(table-cells-styless tl)))
tl
#f))))
;; Merge:
(define (cons-maybe v l) (if v (cons v l) l))
(make-style (style-name s)
(cons-maybe
(and all-column-properties
(table-columns
(if tc
(for/list ([ps (in-list all-column-properties)]
[cs (in-list (table-columns-styles tc))])
(make-style (style-name cs)
(append ps (style-properties cs))))
(for/list ([ps (in-list all-column-properties)])
(make-style #f ps)))))
(cons-maybe
(and all-cell-properties
(table-cells
(if tl
(for/list ([pss (in-list all-cell-properties)]
[css (in-list (table-cells-styless tl))])
(for/list ([ps (in-list pss)]
[cs (in-list css)])
(make-style (style-name cs)
(append ps (style-properties cs)))))
(for/list ([pss (in-list all-cell-properties)])
(for/list ([ps (in-list pss)])
(make-style #f ps))))))
(remq tc (remq tl props))))))
;; Process cells:
(map (lambda (row)
(define (cvt cell)
(cond
[(eq? cell 'cont) cell]
[(block? cell) cell]
[else (make-paragraph plain cell)]))
(define l (map cvt row))
(if sep
(add-between/cont l (cvt sep))
l))
cells)))
;; Like `add-between`, but change `sep` to 'cont when
;; adding before a 'cont:
(define (add-between/cont l sep)
(cond
[(null? l) null]
[(null? (cdr l)) l]
[else
(list* (car l)
(if (eq? 'cont (cadr l)) 'cont sep)
(add-between/cont (cdr l) sep))]))
;; ----------------------------------------
(provide/contract
[elemtag (->* ((or/c tag? string?))
()
#:rest (listof pre-content?)
element?)]
[elemref (->* ((or/c tag? string?))
(#:underline? any/c)
#:rest (listof pre-content?)
element?)]
[secref (->* (string?)
(#:doc module-path?
#:tag-prefixes (or/c #f (listof string?))
#:underline? any/c)
element?)]
[Secref (->* (string?)
(#:doc module-path?
#:tag-prefixes (or/c #f (listof string?))
#:underline? any/c)
element?)]
[seclink (->* (string?)
(#:doc module-path?
#:tag-prefixes (or/c #f (listof string?))
#:underline? any/c
#:indirect? any/c)
#:rest (listof pre-content?)
element?)]
[other-doc (->* (module-path?)
(#:underline? any/c
#:indirect (or/c #f content?))
element?)])
(define (elemtag t . body)
(make-target-element #f (decode-content body) `(elem ,t)))
(define (elemref #:underline? [u? #t] t . body)
(make-link-element (if u? #f "plainlink") (decode-content body) `(elem ,t)))
(define (secref s #:underline? [u? #t] #:doc [doc #f] #:tag-prefixes [prefix #f])
(make-link-element (if u? #f "plainlink") null (make-section-tag s #:doc doc #:tag-prefixes prefix)))
(define (Secref s #:underline? [u? #t] #:doc [doc #f] #:tag-prefixes [prefix #f])
(let ([le (secref s #:underline? u? #:doc doc #:tag-prefixes prefix)])
(make-link-element
(make-style (element-style le) '(uppercase))
(element-content le)
(link-element-tag le))))
(define normal-indirect (style #f '(indirect-link)))
(define plain-indirect (style "plainlink" '(indirect-link)))
(define (seclink tag
#:doc [doc #f]
#:underline? [u? #t]
#:tag-prefixes [prefix #f]
#:indirect? [indirect? #f]
. s)
(make-link-element (if indirect?
(if u?
normal-indirect
plain-indirect)
(if u?
#f
"plainlink"))
(decode-content s)
`(part ,(doc-prefix doc prefix tag))))
(define (other-doc doc
#:underline? [u? #t]
#:indirect [indirect #f])
(if indirect
(seclink "top" #:doc doc #:underline? u? #:indirect? #t
(list "the " indirect " documentation"))
(secref "top" #:doc doc #:underline? u?)))
;; ----------------------------------------
(provide/contract
[hyperlink (->* ((or/c string? path?))
(#:underline? any/c
#:style element-style?)
#:rest (listof pre-content?)
element?)]
[url (-> string? element?)]
[margin-note (->* () (#:left? any/c) #:rest (listof pre-flow?) block?)]
[margin-note* (->* () (#:left? any/c) #:rest (listof pre-content?) element?)]
[centered (->* () () #:rest (listof pre-flow?) block?)]
[verbatim (->* (content?) (#:indent exact-nonnegative-integer?) #:rest (listof content?) block?)])
(define (centered . s)
(make-nested-flow (make-style "SCentered" null) (decode-flow s)))
(define (hyperlink url
#:underline? [underline? #t]
#:style [style (if underline? #f "plainlink")]
. str)
(make-element (make-style (if (style? style)
(style-name style)
style)
(cons (make-target-url url)
(if (style? style)
(style-properties style)
null)))
(decode-content str)))
(define (url str)
(hyperlink str (make-element 'url str)))
(define (margin-note #:left? [left? #f] . c)
(make-nested-flow
(make-style (if left? "refparaleft" "refpara")
'(command never-indents))
(list
(make-nested-flow
(make-style (if left? "refcolumnleft" "refcolumn")
null)
(list
(make-nested-flow
(make-style "refcontent" null)
(decode-flow c)))))))
(define (margin-note* #:left? [left? #f] . c)
(make-element
(make-style (if left? "refelemleft" "refelem") null)
(make-element
(make-style (if left? "refcolumnleft" "refcolumn") null)
(make-element
(make-style "refcontent" null)
(decode-content c)))))
(define (verbatim #:indent [i 0] s . more)
(define lines
;; Break input into a list of lists, where each inner
;; list is a single line. Break lines on "\n" in the
;; input strings, while non-string content is treated
;; as an element within a line.
(let loop ([l (cons s more)] [strs null])
(cond
[(null? l) (if (null? strs)
null
(map
list
(regexp-split
#rx"\n"
(apply string-append (reverse strs)))))]
[(string? (car l))
(loop (cdr l) (cons (car l) strs))]
[else
(define post-lines (loop (cdr l) null))
(define pre-lines (loop null strs))
(define-values (post-line rest-lines)
(if (null? post-lines)
(values null null)
(values (car post-lines) (cdr post-lines))))
(define-values (first-lines pre-line)
(if (null? pre-lines)
(values null null)
(values (drop-right pre-lines 1)
(last pre-lines))))
(append first-lines
(list (append pre-line (list (car l)) post-line))
rest-lines)])))
(define (str->elts str)
;; Convert a single string in a line to typewriter font,
;; and also convert multiple adjacent spaces to `hspace` so
;; that the space is preserved exactly:
(let ([spaces (regexp-match-positions #rx"(?:^| ) +" str)])
(if spaces
(list* (make-element 'tt (substring str 0 (caar spaces)))
(hspace (- (cdar spaces) (caar spaces)))
(str->elts (substring str (cdar spaces))))
(list (make-element 'tt (list str))))))
(define (strs->elts line)
;; Convert strings in the line:
(apply append (map (lambda (e)
(if (string? e)
(str->elts e)
(list e)))
line)))
(define indent
;; Add indentation to a line:
(if (zero? i)
values
(let ([hs (hspace i)]) (lambda (line) (cons hs line)))))
(define (make-nonempty l)
;; If a line has no content, then add a single space:
(if (let loop ([l l])
(cond
[(null? l) #t]
[(equal? "" l) #t]
[(list? l) (andmap loop l)]
[(element? l) (loop (element-content l))]
[(multiarg-element? l) (loop (multiarg-element-contents l))]
[else #f]))
(list l (hspace 1))
l))
(define (make-line line)
;; Convert a list of line elements --- a mixture of strings
;; and non-strings --- to a paragraph for the line:
(let* ([line (indent (strs->elts line))])
(list (make-paragraph omitable-style (make-nonempty line)))))
(make-table plain (map make-line lines)))
(define omitable-style (make-style 'omitable null))
;; ----------------------------------------
; XXX unknown contract
(provide get-index-entries)
(provide/contract
[index-block (-> delayed-block?)]
[index (((or/c string? (listof string?))) () #:rest (listof pre-content?) . ->* . index-element?)]
[index* (((listof string?) (listof any/c)) () #:rest (listof pre-content?) . ->* . index-element?)] ; XXX first any/c wrong in docs
[as-index (() () #:rest (listof pre-content?) . ->* . index-element?)]
[section-index (() () #:rest (listof string?) . ->* . part-index-decl?)]
[index-section (() (#:tag (or/c false/c string?)) . ->* . part?)])
(define (section-index . elems)
(make-part-index-decl (map content->string elems) elems))
(define (record-index word-seq element-seq tag content)
(make-index-element #f
(list (make-target-element #f content `(idx ,tag)))
`(idx ,tag)
word-seq
element-seq
#f))
(define (index* word-seq content-seq . s)
(let ([key (make-generated-tag)])
(record-index (map clean-up-index-string word-seq)
content-seq key (decode-content s))))
(define (index word-seq . s)
(let ([word-seq (if (string? word-seq) (list word-seq) word-seq)])
(apply index* word-seq word-seq s)))
(define (as-index . s)
(let ([key (make-generated-tag)]
[content (decode-content s)])
(record-index
(list (clean-up-index-string (content->string content)))
(if (= 1 (length content)) content (list (make-element #f content)))
key
content)))
(define (index-section #:title [title "Index"] #:tag [tag #f])
(make-part #f
`((part ,(or tag "doc-index")))
(list title)
(make-style 'index '(unnumbered))
null
(list (index-block))
null))
;; returns an ordered list of (list tag (text ...) (element ...) index-desc)
(define (get-index-entries sec ri)
(define (compare-lists xs ys <?)
(let loop ([xs xs] [ys ys])
(cond [(and (null? xs) (null? ys)) '=]
[(null? xs) '<]
[(null? ys) '>]
[(<? (car xs) (car ys)) '<]
[(<? (car ys) (car xs)) '>]
[else (loop (cdr ys) (cdr xs))])))
;; string-ci<? as a major key, and string<? next, so "Foo" precedes "foo"
;; (define (string*<? s1 s2)
;; (or (string-ci<? s1 s2)
;; (and (not (string-ci<? s2 s1)) (string<? s1 s2))))
(define (get-desc entry)
(let ([desc (cadddr entry)])
(cond [(exported-index-desc? desc)
(cons 'libs (map (lambda (l)
(format "~s" l))
(exported-index-desc-from-libs desc)))]
[(module-path-index-desc? desc) '(mod)]
[(part-index-desc? desc) '(part)]
[(delayed-index-desc? desc) '(delayed)]
[else '(#f)])))
;; parts first, then modules, then bindings, delayed means it's not
;; the last round, and #f means no desc
(define desc-order '(part mod libs delayed #f))
;; this defines an imposed ordering for module names
(define lib-order '(#rx"^racket(?:/|$)" #rx"^r.rs(?:/|$)" #rx"^lang(?:/|$)"))
(define (lib<? lib1 lib2)
(define (lib-level lib)
(let loop ([i 0] [rxs lib-order])
(if (or (null? rxs) (regexp-match? (car rxs) lib))
i (loop (add1 i) (cdr rxs)))))
(let ([l1 (lib-level lib1)] [l2 (lib-level lib2)])
(if (= l1 l2) (string<? lib1 lib2) (< l1 l2))))
(define (compare-desc e1 e2)
(let* ([d1 (get-desc e1)] [d2 (get-desc e2)]
[t1 (car d1)] [t2 (car d2)])
(cond [(memq t2 (cdr (memq t1 desc-order))) '<]
[(memq t1 (cdr (memq t2 desc-order))) '>]
[else (case t1 ; equal to t2
[(part) '=] ; will just compare tags
[(mod) '=] ; the text fields are the names of the modules
[(libs) (compare-lists (cdr d1) (cdr d2) lib<?)]
[(delayed) '>] ; dosn't matter, will run again
[(#f) '=])])))
(define (entry<? e1 e2)
(let ([text1 (cadr e1)] [text2 (cadr e2)])
(case (compare-lists text1 text2 string-ci<?)
[(<) #t] [(>) #f]
[else (case (compare-desc e1 e2)
[(<) #t] [(>) #f]
[else (case (compare-lists text1 text2 string<?)
[(<) #t] [(>) #f]
[else
;; (error 'get-index-entries
;; ;; when this happens, revise this code so
;; ;; ordering will always be deterministic
;; "internal error -- unordered entries: ~e ~e"
;; e1 e2)
;; Instead, just compare the tags
(string<? (format "~a" (car e1))
(format "~a" (car e2)))])])])))
(define l null)
(hash-for-each
(let ([parent (collected-info-parent (part-collected-info sec ri))])
(if parent
(collected-info-info (part-collected-info parent ri))
(let ([ci (resolve-info-ci ri)])
;; Force all xref info:
((collect-info-ext-demand ci) #f ci)
(collect-info-ext-ht ci))))
(lambda (k v)
(when (and (pair? k) (eq? 'index-entry (car k)))
(let ([v (if (known-doc? v) (known-doc-v v) v)])
(set! l (cons (cons (cadr k) v) l))))))
(sort l entry<?))
(define (index-block)
(define alpha (string->list "ABCDEFGHIJKLMNOPQRSTUVWXYZ"))
(define (rows . rows)
(make-table (make-style 'index null)
(map (lambda (row)
(list (make-paragraph plain row)))
rows)))
(define contents
(lambda (renderer sec ri)
(define l (get-index-entries sec ri))
(define manual-newlines? (send renderer index-manual-newlines?))
(define alpha-starts (make-hasheq))
(define alpha-row
(let loop ([i l] [alpha alpha])
(define (add-letter let l)
(list* (make-element "nonavigation" (list (string let))) " " l))
(cond [(null? alpha) null]
[(null? i) (add-letter (car alpha) (loop i (cdr alpha)))]
[else
(let* ([strs (cadr (car i))]
[letter (if (or (null? strs) (string=? "" (car strs)))
#f
(char-upcase (string-ref (car strs) 0)))])
(cond [(not letter) (loop (cdr i) alpha)]
[(char-ci>? letter (car alpha))
(add-letter (car alpha) (loop i (cdr alpha)))]
[(char-ci=? letter (car alpha))
(hash-set! alpha-starts (car i) letter)
(list* (make-element
(make-style #f (list (make-target-url (format "#alpha:~a" letter))))
(list (string (car alpha))))
" "
(loop (cdr i) (cdr alpha)))]
[else (loop (cdr i) alpha)]))])))
(define body
(let ([br (if manual-newlines? (make-element 'newline '("\n")) "")])
(map (lambda (i)
(let ([e (make-link-element
"indexlink"
`(,@(add-between (caddr i) ", ") ,br)
(car i))])
(cond [(hash-ref alpha-starts i #f)
=> (lambda (let)
(make-element
(make-style #f (list
(make-url-anchor
(format "alpha:~a" (char-upcase let)))))
(list e)))]
[else e])))
l)))
(if manual-newlines?
(rows alpha-row '(nbsp) body)
(apply rows alpha-row '(nbsp) (map list body)))))
(make-delayed-block contents))
;; ----------------------------------------
(provide/contract
[table-of-contents (-> delayed-block?)]
[local-table-of-contents (()
(#:style (or/c style? string? symbol? (listof symbol?) #f))
. ->* . delayed-block?)])
(define (table-of-contents)
(make-delayed-block
(lambda (renderer part ri)
(send renderer table-of-contents part ri))))
(define (local-table-of-contents #:style [style plain])
(make-delayed-block
(lambda (renderer part ri)
(send renderer local-table-of-contents part ri style))))

4
scribble-lib/scribble/base/lang.rkt
View File

@ -1,4 +0,0 @@
#lang racket/base
(require scribble/doclang scribble/base)
(provide (all-from-out scribble/doclang
scribble/base))

3
scribble-lib/scribble/base/lang/reader.rkt
View File

@ -1,3 +0,0 @@
#lang s-exp scribble/base/reader
scribble/base/lang
#:wrapper1 (lambda (t) (list* 'doc 'values '() (t)))

46
scribble-lib/scribble/basic.rkt
View File

@ -1,46 +0,0 @@
#lang scheme/base
(require "base.rkt"
"core.rkt"
"decode.rkt")
(provide title
section
subsection
subsubsection
subsubsub*section
include-section
author
author+email
intern-taglet
module-path-index->taglet
module-path-prefix->string
itemize item item?
hspace
elem aux-elem
italic bold smaller
tt
subscript superscript
section-index index index* as-index index-section
get-index-entries index-block
table-of-contents
local-table-of-contents
span-class)
(define (span-class classname . str)
(make-element classname (decode-content str)))
(define (aux-elem . s)
(make-element (make-style #f (list 'aux)) (decode-content s)))
(define (itemize #:style [style #f] . items)
(let ([items (filter (lambda (v) (not (whitespace? v))) items)])
(apply itemlist #:style style items)))

198
scribble-lib/scribble/blueboxes.rkt
View File

@ -1,198 +0,0 @@
#lang typed/racket/base
(require racket/match)
(require/typed setup/dirs [get-doc-search-dirs (-> (Listof Path))])
(require/typed racket/serialize [deserialize (Any -> Any)])
(require/typed scribble/core [#:opaque Tag tag?])
(require/typed scribble/tag
[#:opaque Method-Tag method-tag?]
[#:opaque Definition-Tag definition-tag?]
[#:opaque Class/Interface-Tag class/interface-tag?]
[class/interface-tag->constructor-tag (Class/Interface-Tag -> Tag)]
[definition-tag->class/interface-tag (Definition-Tag -> Class/Interface-Tag)]
[get-class/interface-and-method (Method-Tag -> (values Symbol Symbol))]
)
(require/typed "valid-blueboxes-info.rkt" [valid-blueboxes-info? (Any -> Boolean)])
(provide fetch-blueboxes-strs
make-blueboxes-cache
blueboxes-cache?
fetch-blueboxes-method-tags
)
(define-type Bluebox-Info bluebox-info)
(struct bluebox-info
([blueboxes.rktd : Path-String]
[offset : (U Natural #f)]
[tag-ht : (U Blueboxes-Info-Hash #f)] ; (or/c valid-blueboxes-info? #f)
[mod-time : (U Natural #f)])
#:mutable)
(define-type Blueboxes-Cache blueboxes-cache)
(struct blueboxes-cache
([info-or-paths : (U (Listof Path) (Listof Bluebox-Info))]
[method->tags : (U (HashTable Symbol (Listof Method-Tag)) #f)])
#:mutable)
(: make-blueboxes-cache :
Boolean
[#:blueboxes-dirs (Listof Path)]
->
Blueboxes-Cache)
(define (make-blueboxes-cache
populate?
#:blueboxes-dirs
[blueboxes-dirs (for*/list ([d (in-list (get-doc-search-dirs))]
[c (in-list (if (directory-exists? d)
(directory-list d)
'()))])
: (Listof Path)
(build-path d c))])
(define cache (blueboxes-cache blueboxes-dirs #f))
(when populate? (populate-cache! cache))
cache)
(: fetch-blueboxes-strs :
Tag
[#:blueboxes-cache Blueboxes-Cache]
->
(U #f (List* String (Listof String))))
(define (fetch-blueboxes-strs tag #:blueboxes-cache [cache (make-blueboxes-cache #f)])
(define plain-strs (fetch-strs-for-single-tag tag cache))
(cond
[(and plain-strs (definition-tag? tag))
(define constructor-strs
(fetch-strs-for-single-tag
(class/interface-tag->constructor-tag
(definition-tag->class/interface-tag tag))
cache))
(append plain-strs
(if constructor-strs '("") '())
(if constructor-strs (cdr constructor-strs) '()))]
[else plain-strs]))
(: fetch-strs-for-single-tag : Tag Blueboxes-Cache -> (U #f (List* String (Listof String))))
(define (fetch-strs-for-single-tag tag cache)
(populate-cache! cache)
(for/or ([ent (in-list (blueboxes-cache-info-or-paths cache))])
: (U #f (List* String (Listof String)))
(when (bluebox-info? ent)
(check-and-update-bluebox-info! ent))
(match ent
[(bluebox-info blueboxes.rktd offset tag-ht _)
(define offset+lens (and tag-ht (hash-ref tag-ht tag #f)))
(cond
[offset+lens
(define lines
(apply
append
(for/list ([offset+len (in-list offset+lens)])
: (Listof (Listof (U String EOF)))
(call-with-input-file blueboxes.rktd
(λ ([port : Input-Port])
(port-count-lines! port)
(file-position port (+ (car offset+len) (or offset 0)))
(for/list ([i (in-range (cdr offset+len))])
: (Listof (U String EOF))
(read-line port)))))))
(cond
[(not (andmap string? lines)) #f]
[(null? lines) #f]
[else lines])]
[else #f])]
[_ (log-warning "expected bluebox-info?, given: ~v" ent)
#f])))
(: fetch-blueboxes-method-tags : Symbol [#:blueboxes-cache Blueboxes-Cache] -> (Listof Method-Tag))
(define (fetch-blueboxes-method-tags sym #:blueboxes-cache [cache (make-blueboxes-cache #f)])
(populate-cache! cache)
(define ht (blueboxes-cache-method->tags cache))
(or (and ht (hash-ref ht sym (λ () '()))) '()))
(define listof-path? (make-predicate (Listof Path)))
(: populate-cache! : Blueboxes-Cache -> Void)
(define (populate-cache! cache)
(define cache-content (blueboxes-cache-info-or-paths cache))
(when (listof-path? cache-content)
(define the-cache (build-blueboxes-cache cache-content))
(define mtd-table (compute-methods-table the-cache))
(set-blueboxes-cache-method->tags! cache mtd-table)
(set-blueboxes-cache-info-or-paths! cache the-cache)))
(: compute-methods-table : (Listof Bluebox-Info) -> (HashTable Symbol (Listof Method-Tag)))
(define (compute-methods-table lst)
(: meth-ht : (HashTable Symbol (Listof Method-Tag)))
(define meth-ht (make-hash))
(for ([a-bluebox-info (in-list lst)])
(match a-bluebox-info
[(bluebox-info blueboxes.rktd offset tag-ht mod-time)
(when tag-ht
(for ([(tag val) (in-hash tag-ht)])
(when (method-tag? tag)
(define-values (class/intf meth) (get-class/interface-and-method tag))
(hash-set! meth-ht meth (cons tag (hash-ref meth-ht meth (λ () '())))))))]))
meth-ht)
(: build-blueboxes-cache : (Listof Path) -> (Listof Bluebox-Info))
(define (build-blueboxes-cache blueboxes-dirs)
(filter
values
(for*/list ([doc-dir-name (in-list blueboxes-dirs)])
: (Listof Bluebox-Info)
(define blueboxes.rktd (build-path doc-dir-name "blueboxes.rktd"))
(define a-bluebox-info (bluebox-info blueboxes.rktd #f #f #f))
(populate-bluebox-info! a-bluebox-info)
a-bluebox-info)))
(: check-and-update-bluebox-info! : bluebox-info -> Void)
(define (check-and-update-bluebox-info! a-bluebox-info)
(match a-bluebox-info
[(bluebox-info blueboxes.rktd offset tag-ht mod-time)
(when (or (not mod-time)
(and (file-exists? blueboxes.rktd)
(not (mod-time . = . (file-or-directory-modify-seconds blueboxes.rktd)))))
(populate-bluebox-info! a-bluebox-info))]))
(: populate-bluebox-info! : Bluebox-Info -> Void)
(define (populate-bluebox-info! a-bluebox-info)
(define blueboxes.rktd (bluebox-info-blueboxes.rktd a-bluebox-info))
(cond
[(file-exists? blueboxes.rktd)
(call-with-input-file blueboxes.rktd
(λ ([port : Input-Port])
(port-count-lines! port)
(define first-line (read-line port))
(define pos (file-position port))
(define desed
(with-handlers ([exn:fail? (λ ([x : exn:fail])
(log-warning "Failed to deserialize ~a: ~a"
x
(exn-message x))
#f)])
(define candidate (deserialize (read port)))
(unless (valid-blueboxes-info? candidate)
(error 'build-blueboxes-cache
"blueboxes info didn't have the right shape: ~s"
candidate))
(cast candidate Blueboxes-Info-Hash)))
(define first-line-num (and (string? first-line) (string->number first-line)))
(cond
[(exact-nonnegative-integer? first-line-num)
(set-bluebox-info-offset! a-bluebox-info (+ first-line-num pos))]
[else
(log-warning "expected a string representing a Natuaral\n given: ~v"
first-line-num)])
(set-bluebox-info-tag-ht! a-bluebox-info desed)
(set-bluebox-info-mod-time! a-bluebox-info
(file-or-directory-modify-seconds blueboxes.rktd))))]
[else
(set-bluebox-info-offset! a-bluebox-info #f)
(set-bluebox-info-tag-ht! a-bluebox-info #f)
(set-bluebox-info-mod-time! a-bluebox-info #f)]))
(define-type Blueboxes-Info-Hash
(HashTable
Tag
(Listof (Pairof Natural
Natural))))

93
scribble-lib/scribble/bnf.rkt
View File

@ -1,93 +0,0 @@
(module bnf racket
(require "struct.rkt"
"decode.rkt"
(only-in "core.rkt"
make-style
make-table-columns)
mzlib/kw)
(provide BNF
nonterm
BNF-seq BNF-seq-lines
BNF-alt BNF-alt/close ; single-line alternatives
BNF-etc
BNF-group
optional kleenestar kleeneplus kleenerange)
(define spacer (make-element 'hspace (list " ")))
(define equals (make-element 'tt (list spacer "::=" spacer)))
(define alt (make-element 'tt (list spacer spacer "|" spacer spacer)))
(define (as-flow i) (make-flow (list (if (block? i)
i
(make-paragraph (list i))))))
(define baseline (make-style #f '(baseline)))
(define (BNF . defns)
(make-table
(make-style #f
(list
(make-table-columns
(list baseline baseline baseline baseline))))
(apply
append
(map (lambda (defn)
(cons
(list (as-flow spacer) (as-flow (car defn)) (as-flow equals) (as-flow (cadr defn)))
(map (lambda (i)
(list (as-flow spacer) (as-flow " ") (as-flow alt) (as-flow i)))
(cddr defn))))
defns))))
(define (interleave l spacer)
(make-element #f (cons (car l)
(apply append
(map (lambda (i)
(list spacer i))
(cdr l))))))
(define (BNF-seq . l)
(if (null? l)
""
(interleave l spacer)))
(define (BNF-seq-lines . l)
(make-table #f (map (lambda (row) (list (as-flow (apply BNF-seq row))))
l)))
(define (BNF-alt . l)
(interleave l alt))
(define (BNF-alt/close . l)
(interleave l (make-element 'roman " | ")))
(define BNF-etc (make-element 'roman "..."))
(define/kw (nonterm #:body s)
(make-element 'roman (append (list 'lang)
(list (make-element 'italic (decode-content s)))
(list 'rang))))
(define/kw (optional #:body s)
(make-element #f (append (list (make-element 'roman "["))
(decode-content s)
(list (make-element 'roman "]")))))
(define/kw (BNF-group #:body s)
(make-element #f (append (list (make-element 'roman "{"))
(list (apply BNF-seq (decode-content s)))
(list (make-element 'roman "}")))))
(define/kw (kleenestar #:body s)
(make-element #f (append (decode-content s) (list (make-element 'roman "*")))))
(define/kw (kleeneplus #:body s)
(make-element #f (append (decode-content s) (list (make-element 'superscript (list "+"))))))
(define/kw (kleenerange a b #:body s)
(make-element #f (append (decode-content s)
(list (make-element 'roman
(make-element 'superscript
(list (format "{~a,~a}" a b)))))))))

Some files were not shown because too many files have changed in this diff Show More