3.1 Base Document Format

3.1 Base Document Format
Scribble:
The Racket Documentation Tool
Getting Started
@ Syntax
High-
Level Scribble API
Scribbling Documentation
Literate Programming
Low-
Level Scribble API
Running
scribble
Index
High-
Level Scribble API
3.1
Base Document Format
3.2
Racket Manual Format
3.3
Book Format
3.4
Report Format
3.5
SIGPLAN Paper Format
3.6
ACM Paper Format
3.7
JFP Paper Format
3.8
LNCS Paper Format
3.1
Base Document Format
3.1.1
Document Structure
3.1.2
Blocks
3.1.3
Text Styles and Content
3.1.4
Images
3.1.5
Spacing
3.1.6
Links
3.1.7
Indexing
3.1.8
Tables of Contents
3.1.9
Tags
On this page:
3.1.1
Document Structure
title
section
subsection
subsubsection
subsubsub*section
include-
section
author
author+
email
3.1.2
Blocks
para
nested
centered
margin-
note
margin-
note*
itemlist
items/
item
item?
tabular
verbatim
3.1.3
Text Styles and Content
elem
italic
bold
tt
subscript
superscript
smaller
larger
emph
literal
3.1.4
Images
image
3.1.5
Spacing
linebreak
nonbreaking
hspace
?-
._
._
3.1.6
Links
hyperlink
url
secref
Secref
seclink
other-
doc
elemtag
elemref
3.1.7
Indexing
index
index*
as-
index
section-
index
index-
section
3.1.8
Tables of Contents
table-
of-
contents
local-
table-
of-
contents
3.1.9
Tags
Racket
top
contents
← prev
up
next →
3.1
Base Document Format
#lang
scribble/base
package:
scribble-lib
The
scribble/base
language provides functions and forms that can be used from code
written either in Racket or with @ expressions. It
essentially extends
racket/base
, except that top-level
forms within a module using the
scribble/base
language
are treated as document content (like
scribble/doclang
).
The
scribble/base
name can also be used as a library
with
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
title
and
italic
, might be called from Racket as
title
#:tag
"how-to"
"How to Design "
italic
"Great"
" Programs"
They can also be called with @ notation as
@title[#:tag "how-to"]{How to Design @italic{Great} Programs}
Although the procedures are mostly designed to be used from @
mode, they are easier to document in Racket mode (partly because we
have
scribble/manual
).
3.1.1
Document Structure
procedure
title
#:tag
tag
#:tag-prefix
tag-prefix
#:style
style
#:version
vers
#:date
date
pre-content
...+
title-decl?
tag
or/c
#f
string?
listof
string?
#f
tag-prefix
or/c
#f
string?
module-path?
hash?
#f
style
or/c
style?
#f
string?
symbol?
listof
symbol?
#f
vers
or/c
string?
#f
#f
date
or/c
string?
#f
#f
pre-content
pre-content?
Generates a
title-decl
to be picked up by
decode
or
decode-part
. The
decode
pre-content
(i.e.,
parsed with
decode-content
) supplies the title content. If
tag
is
#f
, a tag string is generated automatically
from the content. The tag string is combined with the symbol
part
to form the full tag.
The
style
argument can be a style structure, or it can be one
of the following: a
#f
that corresponds to a “plain” style,
a string that is used as a
style name
, a symbol that is used as
style property
, or a list of symbols to be used as
style properties
For information on styles, see
part
. For example, a style of
toc
causes sub-sections to be generated as separate pages in
multi-page HTML output.
The
tag-prefix
argument is propagated to the generated
structure (see
Tags
). If
tag-prefix
is a module
path, it is converted to a string using
module-path-prefix->string
. Similarly, if
tag-prefix
is a hash table with
tag-prefix
mapped to a module path,
then it is replaced with a hash table where
tag-prefix
is
mapped to a string. When
tag-prefix
as a hash table is
used for the main part in a document rendered by
raco setup
raco setup
uses some keys to configure the document’s
rendering; see
scribblings
in
Controlling
raco setup
with
"info.rkt"
Files
for more information.
The
vers
argument is propagated to the
title-decl
structure. Use
""
as
vers
to suppress version
rendering in the output.
The
date
argument is propagated to the
title-decl
structure via a
document-date
style property
. Use
""
as
date
to suppress date rendering in Latex
output.
The section title is automatically indexed by
decode-part
. For the index key, leading whitespace and a
leading “A”, “An”, or “The” (followed by more whitespace) is
removed.
procedure
section
#:tag
tag
#:tag-prefix
tag-prefix
#:style
style
pre-content
...+
part-start?
tag
or/c
#f
string?
listof
string?
#f
tag-prefix
or/c
#f
string?
module-path?
hash?
#f
style
or/c
style?
#f
string?
symbol?
listof
symbol?
#f
pre-content
pre-content?
Like
title
, but
generates a
part-start
of depth
to be picked up by
decode
or
decode-part
procedure
subsection
#:tag
tag
#:tag-prefix
tag-prefix
#:style
style
pre-content
...+
part-start?
tag
or/c
#f
string?
listof
string?
#f
tag-prefix
or/c
#f
string?
module-path?
hash?
#f
style
or/c
style?
#f
string?
symbol?
listof
symbol?
#f
pre-content
pre-content?
Like
section
, but
generates a
part-start
of depth
procedure
subsubsection
#:tag
tag
#:tag-prefix
tag-prefix
#:style
style
pre-content
...+
part-start?
tag
or/c
#f
string?
listof
string?
#f
tag-prefix
or/c
#f
string?
module-path?
hash?
#f
style
or/c
style?
#f
string?
symbol?
listof
symbol?
#f
pre-content
pre-content?
Like
section
, but
generates a
part-start
of depth
procedure
subsubsub*section
#:tag
tag
pre-content
...+
paragraph?
tag
or/c
#f
string?
listof
string?
#f
pre-content
pre-content?
Similar to
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).
syntax
include-section
module-path
Requires
module-path
and returns its
doc
export (without making any imports
visible to the enclosing context). Since this form expands to
require
, it must be used in a module or top-level context.
procedure
author
auth
...
block?
auth
content?
Generates a
paragraph
with style name
author
to
show the author(s) of a document, where each author is represented by
content
. Normally, this function is used after
title
for the beginning of a document. See also
author+email
Examples:
author
Alice
P.
Racketeer
procedure
author+email
author-name
email
#:obfuscate?
obfuscate?
element?
author-name
content?
email
string?
obfuscate?
any/c
#f
Combines an author name with an e-mail address. If
obfuscate?
is true, then the result obscures the e-mail address slightly to avoid
address-harvesting robots.
Note that
author+email
is not a replacement for
author
. The
author+email
function is often used in
combination with
author
Examples:
author
author+email
"Bob
T.
Scribbler"
"bob@racket-lang.org"
3.1.2
Blocks
procedure
para
#:style
style
pre-content
...
paragraph?
style
or/c
style?
string?
symbol?
#f
#f
pre-content
pre-content?
Creates a
paragraph
containing the
decode
pre-content
(i.e., parsed with
decode-paragraph
).
The
style
argument can be a style,
#f
to indicate a
“plain” style, a string that is used as a
style name
, or a
symbol that is used as a
style name
. (Note that
section
and
para
treat symbols differently as
style
arguments.)
procedure
nested
#:style
style
pre-flow
...
nested-flow?
style
or/c
style?
string?
symbol?
#f
#f
pre-flow
pre-flow?
Creates a
nested flow
containing the
decode
pre-flow
(i.e., parsed with
decode-flow
).
The
style
argument is handled the same as
para
. The
inset
and
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).
procedure
centered
pre-flow
...
nested-flow?
pre-flow
pre-flow?
Produces a
nested flow
whose content is centered.
procedure
margin-note
pre-flow
...
#:left?
left?
#:footnote?
footnote?
block?
pre-flow
pre-flow?
left?
any/c
#f
footnote?
any/c
#f
Produces a
nested flow
that is typeset in the margin, instead
of inlined.
If
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.
If
footnote?
is true, then the Latex renderer typesets the
content as a footnote instead of a margin note.
Changed in version 1.55 of package
scribble-lib
: Added the
#:footnote?
argument.
procedure
margin-note*
pre-content
...
#:left?
left?
#:footnote?
footnote?
element?
pre-content
pre-content?
left?
any/c
#f
footnote?
any/c
#f
Like
margin-note
, but
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.
Changed in version 1.55 of package
scribble-lib
: Added the
#:footnote?
argument.
procedure
itemlist
itm
...
#:style
style
itemization?
itm
items/c
style
or/c
style?
string?
symbol?
#f
#f
Constructs an
itemization
given a sequence of items. Typical
each
itm
is constructed by
item
, but an
itm
can be a
block
that is coerced to an
item
. Finally,
itm
can be a list or
splice
whose elements are spliced (recursively, if necessary) into the
itemlist
sequence.
The
style
argument is handled the same as
para
. The
ordered
style numbers items, instead of just using a
bullet.
value
items/c
flat-contract?
A contract that is equivalent to the following recursive
specification:
or/c
item?
block?
listof
items/c
spliceof
items/c
procedure
item
pre-flow
...
item?
pre-flow
pre-flow?
Creates an item for use with
itemlist
. The
decode
pre-flow
(i.e., parsed with
decode-flow
) is the item
content.
procedure
item?
boolean?
any/c
Returns
#t
if
is an item produced by
item
#f
otherwise.
procedure
tabular
cells
#:style
style
#:pad
pad
#:sep
sep
#:column-properties
column-properties
#:row-properties
row-properties
#:cell-properties
cell-properties
#:sep-properties
sep-properties
table?
cells
listof
listof
or/c
block?
content?
cont
style
or/c
style?
string?
symbol?
#f
#f
pad
or/c
real?
list/c
real?
real?
list/c
real?
real?
real?
real?
sep
or/c
block?
content?
#f
#f
column-properties
listof
any/c
row-properties
listof
any/c
cell-properties
listof
listof
any/c
sep-properties
or/c
list?
#f
#f
Creates a
table
with the given
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
cont
in
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
cont
must not appear as the first
cell in a row.
The
style
argument is handled the same as
para
See
table
for a list of recognized
style names
and
style properties
The default style places no space between table columns. Specify a
pad
list to add padding around each cell’s content, where the
numbers in a
pad
list are in “ex” units (roughly
corresponding to the size of a character). If
pad
is a single
number, it is used for all sides of the cell. If
pad
is a
list of two numbers, the first is used on the left and right, and the
last is used on the top and bottom. If
pad
is a list of four
numbers, they are used in order for left, top, right, and bottom
padding.
If
sep
is not
#f
, it is inserted as a new column
between every column in the table; the new column’s properties are the
same as the preceding column’s, unless
sep-properties
provides a list of
style properties
to use. When
sep
would be placed before a
cont
, a
cont
is inserted,
instead.
The
column-properties
row-properties
, and
cell-properties
arguments specify
style properties
for
the columns and cells of a table; see
table-columns
and
table-cells
for a description of recognized properties. The
lists do not contain entries for columns potentially introduced for
sep
, and when non-empty, they are extended as needed to match
the table size determined by
cells
If the length of
column-properties
is less than the
length of each row in
cells
, the last item of the list
is duplicated to make the list long enough.
If the length of
row-properties
is less than the
length of
cells
, the last item of the list is
duplicated to make the list long enough.
If the length of
cell-properties
is less than the
number of rows in
cells
, then the last element is
duplicated to make the list long enough. Each list within
cell-properties
is treated like a
column-properties
list—
expanded as needed to match
the number of columns in each row.
Each element of
column-properties
or
row-properties
is either a list of
style property
values or a non-list element
that is wrapped as a list. Similarly, for each list that is an element
of
cell-properties
, the list’s non-list elements are wrapped
as nested lists.
If
column-properties
is non-empty, then its list of property
lists is converted into a
table-columns
style property
that is added to the style specified by
style
or merged
with an existing
table-columns
style property
that
matches the column shape of
cells
. In addition, if either
row-properties
or
cell-properties
is non-empty, the
property lists of
column-properties
are merged
with the property lists of
row-properties
and
cell-properties
. If
row-properties
or
cell-properties
is non-empty, the merged lists are
converted into a
table-cells
style property
that is
added to the style specified by
style
or merged with an
existing
table-cells
style property
that matches the
shape of
cells
If the style lists for
column-properties
are
both merged with
cell-properties
and converted to
table-columns
, then
style
will contain some
redundant information. In that case,
column-attributes
properties will be used from
table-columns
, while other
properties will be used from the merger into
table-cells
Examples:
tabular
#:sep
hspace
list
list
"soup"
"gazpacho"
list
"soup"
"tonjiru"
tabular
#:pad
#:column-properties
border
list
list
"gazpacho"
"cold"
list
"tonjiru"
"hot"
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
Renders like:
soup
gazpacho
soup
tonjiru
gazpacho
cold
tonjiru
hot
recipe
vegetable
caldo verde
kale
kinpira gobō
burdock
makizushi
Changed in version 1.1 of package
scribble-lib
: Added the
#:column-properties
#:row-properties
and
#:cell-properties
arguments.
Changed in version 1.12: Changed
sep
insertion before a
cont
Changed in version 1.28: Added the
sep-properties
argument and made
the preceding column’s properties used
consistently if not specified.
Changed in version 1.59: Added the
pad
argument.
procedure
verbatim
#:indent
indent
elem
...+
block?
indent
exact-nonnegative-integer?
elem
content?
Typesets string
elem
s in typewriter font with linebreaks
specified by newline characters in string
elem
s. Consecutive spaces in
the string
elem
s are converted to
hspace
to ensure that they
are all preserved in the output. Additional space (via
hspace
) as specified by
indent
is added to the
beginning of each line. A non-string
elem
is treated as
content within a single line.
The string
elem
s are
not
decoded with
decode-content
so
verbatim
"---"
renders with three hyphens instead of an
em dash. Beware, however, that
reading
verbatim
converts
syntax
within the argument, and such reading occurs well before
arguments to
verbatim
are delivered at run-time. To disable simple
notation within the
verbatim
argument,
verbatim
is typically used with
|{
...
}|
or similar brackets, like this:
@verbatim|{
Use @bold{---} like this...
}|
which renders as
Use @bold{---} like this...
while
@verbatim|{
Use |@bold{---} like this...
}|
renders as
Use
like this...
Even with brackets like
|{
...
}|
, beware that consistent
leading whitespace is removed by the parser; see
Alternative Body Syntax
for more information.
See also
literal
3.1.3
Text Styles and Content
procedure
elem
pre-content
...
#:style
style
element?
pre-content
pre-content?
style
or/c
style?
string?
symbol?
#f
#f
Wraps the
decode
pre-content
as an
element
with style
style
procedure
italic
pre-content
...
element?
pre-content
pre-content?
Like
elem
, but with style
italic
procedure
bold
pre-content
...
element?
pre-content
pre-content?
Like
elem
, but with style
bold
procedure
tt
pre-content
...
element?
pre-content
pre-content?
Similar to
elem
, but the
tt
style is used for
immediate strings and symbols among the
pre-content
arguments.
To apply the
tt
style uniformly to all
pre-content
arguments, use
elem
#:style
tt
pre-content
...
, instead.
procedure
subscript
pre-content
...
element?
pre-content
pre-content?
Like
elem
, but with style
subscript
procedure
superscript
pre-content
...
element?
pre-content
pre-content?
Like
elem
, but with style
superscript
procedure
smaller
pre-content
...
element?
pre-content
pre-content?
Like
elem
, but with style
smaller
. When uses of
smaller
are nested, text
gets progressively smaller.
procedure
larger
pre-content
...
element?
pre-content
pre-content?
Like
elem
, but with style
larger
. When uses of
larger
are nested, text
gets progressively larger.
procedure
emph
pre-content
...
element?
pre-content
pre-content?
Like
elem
, but emphasised. Typically, italics are used for
emphasis. Uses of
emph
can be nested; typically this causes
the text to alternate between italic and upright.
procedure
literal
str
...+
element?
str
string?
Produces an element containing literally
str
s with no
decoding via
decode-content
Beware that
for a
literal
call performs some
processing before delivering arguments to
literal
. The
literal
form can be used with
|{
...
}|
or similar brackets to disable
notation within the
literal
argument, like this:
@literal|{@bold{---}}|
which renders as
@bold{---}
See also
verbatim
3.1.4
Images
procedure
image
path
#:scale
scale
#:suffixes
suffixes
#:style
style
pre-content
...
image-element?
path
or/c
path-string?
cons/c
collects
listof
bytes?
scale
real?
1.0
suffixes
listof
#rx"^[.]"
null
style
or/c
style?
string?
symbol?
#f
#f
pre-content
pre-content?
Creates an image element from the given path. The
decode
pre-content
serves as the alternate text for contexts where
the image cannot be displayed.
If
path
is a relative path, it is relative to the current
directory, which is set by
raco setup
to
the directory of the main document file. (In general, however, it’s
more reliable to express relative paths using
define-runtime-path
.) Instead of a path or string,
the
path
argument can be a result of
path->main-collects-relative
The
scale
argument sets the images scale relative to its
default size as determined by the content of
path
. For HTML
output, the resulting
image-element
is rendered with an
img
or
object
(for SVG) tag, and
scale
adjusts the
width
and
height
attributes; a class name or other
attributes in
style
can effectively override that size.
The strings in
suffixes
are filtered to those supported by
given renderer, and then the acceptable suffixes are tried in
order. The HTML renderer supports
".png"
".gif"
, and
".svg"
, while the Latex renderer supports
".png"
".pdf"
, and
".ps"
(but
".ps"
works only
when converting Latex output to DVI, and
".png"
and
".pdf"
work only for converting Latex output to PDF).
Note that when the
suffixes
list is non-empty, then
the
path
argument should not have a suffix.
Changed in version 1.3 of package
scribble-lib
: Added the
#:style
argument.
3.1.5
Spacing
procedure
linebreak
element?
Produces an element that forces a line break.
procedure
nonbreaking
pre-content
...
element?
pre-content
pre-content?
Like
elem
, but line breaks are
suppressed while rendering the content.
procedure
hspace
element?
exact-nonnegative-integer?
Produces an element containing
spaces and style
hspace
value
string?
A string containing the non-breaking space character,
which is equivalent to
nbsp
as an element.
value
-~
string?
A string containing the non-breaking hyphen character.
value
?-
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).
value
._
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
@._
in a
document instead of just
for an abbreviation-ending period
that is preceded by a lowercase letter and followed by a space.
See
.__
for an example.
value
.__
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
@.__
in a document instead of just
for a sentence-ending period that is preceded by an
uppercase letter.
The following example illustrates both
._
and
.__
#lang
scribble/base
My
name
is
Mr
._
.__
pity
the
fool
who
can't
typeset
punctuation.
3.1.6
Links
procedure
hyperlink
url
pre-content
...
#:underline?
underline?
#:style
style
element?
url
string?
pre-content
pre-content?
underline?
any/c
#t
style
or/c
style?
string?
symbol?
#f
if
underline?
#f
"plainlink"
The
decode
pre-content
is hyperlinked to
url
. If
style
is not supplied, then
underline?
determines how the link is rendered.
procedure
url
dest
element?
dest
string?
Generates a literal hyperlinked URL.
procedure
secref
tag
#:doc
module-path
#:tag-prefixes
prefixes
#:underline?
underline?
#:link-render-style
ref-style
element?
tag
string?
module-path
or/c
module-path?
#f
#f
prefixes
or/c
listof
string?
#f
#f
underline?
any/c
#t
ref-style
or/c
link-render-style?
#f
#f
Inserts a reference to the section tagged
tag
If
#:doc
module-path
is provided, the
tag
refers to
a tag with a prefix determined by
module-path
. When
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,
module-path
would be
lib
"scribblings/reference/reference.scrbl"
The
#:tag-prefixes
prefixes
argument similarly supports
selecting a particular section as determined by a path of tag
prefixes. When a
#:doc
argument is provided, then
prefixes
should trace a path of tag-prefixed subsections to
reach the
tag
section. When
#:doc
is not provided,
the
prefixes
path is relative to any enclosing section (i.e.,
the youngest ancestor that produces a match).
For the result
link-element
, if
ref-style
is not
#f
, then it is attached as a
style property
and
affects the rendering of the link. Alternatively, an enclosing
part
can have a link-render style that adjusts the rendering
style for all links within the
part
. See
link-element
for more information about the rendering of section references.
If
underline?
is
#f
, then a
style
is attached
to the result
link-element
so that the hyperlink is rendered
in HTML without an underline
In Racket documentation that is rendered to HTML, clicking on a
section title normally shows the
secref
call that is needed
to link to the section.
Changed in version 1.25 of package
scribble-lib
: Added the
#:link-render-style
argument.
procedure
Secref
tag
#:doc
module-path
#:tag-prefixes
prefixes
#:underline?
underline?
#:link-render-style
ref-style
element?
tag
string?
module-path
or/c
module-path?
#f
#f
prefixes
or/c
listof
string?
#f
#f
underline?
any/c
#t
ref-style
or/c
link-render-style?
#f
#f
Like
secref
, but if the rendered form of the reference starts
with a word (e.g., “section”), then the word is capitalized.
Changed in version 1.25 of package
scribble-lib
: Added the
#:link-render-style
argument.
procedure
seclink
tag
#:doc
module-path
#:tag-prefixes
prefixes
#:underline?
underline?
#:indirect?
indirect?
pre-content
...
element?
tag
string?
module-path
or/c
module-path?
#f
#f
prefixes
or/c
listof
string?
#f
#f
underline?
any/c
#t
indirect?
any/c
#f
pre-content
pre-content?
Like
secref
, but the link label is the
decode
pre-content
instead of the target section’s name.
In addition to
secref
’s arguments,
seclink
supports
indirect?
argument. When
indirect?
is true, then
the section hyperlink’s resolution in HTML is potentially delayed; see
indirect-link
for
link-element
procedure
other-doc
module-path
#:underline?
underline?
#:indirect
indirect
element?
module-path
module-path?
underline?
any/c
#t
indirect
or/c
#f
content?
#f
Like
secref
for the document’s implicit
"top"
tag that
raco setup
adds to every document that it renders.
Use this function to refer to a whole manual instead of
secref
, in case a special style in the future is used for
manual titles.
If
indirect
is not
#f
, then the link’s resolution in
HTML can be delayed, like
seclink
with
#:indirect?
#t
. The
indirect
content is prefixed with “the” and
suffixed with “documentation” to generate the rendered text of the
link. For example:
@other-doc['(lib "parsack/parsack/parsack.scrbl")
#:indirect "Parsec implementation in Racket"]
renders as a hyperlink with the text:
the Parsec implementation in Racket documentation
procedure
elemtag
pre-content
...
element?
or/c
taglet?
generated-tag?
pre-content
pre-content?
The tag
refers to the content form of
pre-content
procedure
elemref
pre-content
...
#:underline?
underline?
element?
or/c
taglet?
generated-tag?
pre-content
pre-content?
underline?
any/c
#t
The
decode
pre-content
is hyperlinked to
which is normally defined using
elemtag
3.1.7
Indexing
procedure
index
words
pre-content
...
#:extras
extras
index-element?
words
or/c
string?
listof
string?
pre-content
pre-content?
extras
desc-extras/c
hash
Creates an index element given a plain-text string—
or list of
strings for a hierarchy, such as
"strings"
"plain"
for a
“plain” entry below a more general “strings” entry. As index keys,
the strings are “cleaned” using
clean-up-index-string
. The
strings (without clean-up) also serve as the text to render in the
index. The
decode
pre-content
is the text to appear
inline as the index target. The
extras
argument is included
in the generated index element as wrapped by
index-desc
Use
index
when an index entry should point to a specific word
or phrase within the typeset document (i.e., the
pre-content
). Use
section-index
, instead, to create
an index entry that leads to a section, instead of a specific word or
phrase within the section.
Changed in version 1.54 of package
scribble-lib
: Added the
extras
argument.
procedure
index*
words
word-contents
pre-content
...
#:extras
extras
index-element?
words
listof
string?
word-contents
listof
list?
pre-content
pre-content?
extras
desc-extras/c
hash
Like
index
, except that
words
must be a list, and
the list of contents render in the index (in parallel to
words
) is supplied as
word-contents
Changed in version 1.54 of package
scribble-lib
: Added the
extras
argument.
procedure
as-index
pre-content
...
#:extras
extras
index-element?
pre-content
pre-content?
extras
desc-extras/c
hash
Like
index
, but the word to index is determined by applying
content->string
on the
decode
pre-content
Changed in version 1.54 of package
scribble-lib
: Added the
extras
argument.
procedure
section-index
word
...
#:extras
extras
part-index-decl?
word
string?
extras
desc-extras/c
hash
Creates a
part-index-decl*
to be associated with the enclosing
section by
decode
. The
word
s serve as both the keys
and as the rendered forms of the keys within the index. The
extras
hash table is wrapped with
index-desc
for the generated
part-index-decl*
Changed in version 1.54 of package
scribble-lib
: Added the
extras
argument.
procedure
index-section
#:tag
tag
part?
tag
or/c
#f
string?
"doc-index"
Produces a part that shows the index of the enclosing document. The
optional
tag
argument is used as the index section’s tag.
3.1.8
Tables of Contents
procedure
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.
procedure
local-table-of-contents
#:style
style
delayed-block?
style
or/c
symbol?
#f
#f
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
style
argument depends on the output type,
but
immediate-only
normally creates a table of contents that
contains only immediate sub-sections of the enclosing section. See
also the
quiet
style of
part
(i.e., in a
part
structure, not supplied as the
style
argument
to
local-table-of-contents
), which normally suppresses
sub-part entries in a table of contents.
3.1.9
Tags
The exports of
scribble/tag
are all re-exported by
scribble/base
top
contents
← prev
up
next →