3.1 Base Document Format
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 design to be used from @
mode, they are easier to document in Racket mode (partly because we
have scribble/manual).
3.1.1 Document Structure
Generates a
title-decl to be picked up by
decode or
decode-part. The
decoded
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
a 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.
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.
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).
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.
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.
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.
3.1.2 Blocks
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.)
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.
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.
Produces an
element that is typeset in the margin, instead of
inlined. Unlike
margin-note,
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.
The style argument is handled the same as para. The
'ordered style numbers items, instead of just using a
bullet.
Returns
#t if
v is an item produced by
item,
#f otherwise.
Creates a
table with the given content, which is supplies as a
list of rows, where each row has a list of cells. The length of all
rows must match.
Use 'cont 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.
Typesets
strs in typewriter font with the linebreaks
specified by newline characters in
str. Consecutive spaces in
the
strs 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.
The strs 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... |
Even with |{...}|, 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
Wraps the
decoded
pre-content as an element with style
style.
Like
elem, but with style
'italic.
Like
elem, but with style
'bold.
Like
elem, but with style
'tt.
Like
elem, but with style
'subscript.
Like
elem, but with style
'superscript.
Like
elem, but with style
'smaller. When uses of
smaller are nested, text
gets progressively smaller.
Like
elem, but with style
'larger. When uses of
larger are nested, text
gets progressively larger.
Produces an element containing literally
strs 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:
which renders as
See also verbatim.
Creates an image element from the given path. The
decoded
pre-content serves as the alternate text for contexts where
the image cannot be displayed.
The path is relative to the current directory, which is set by
setup-plt and scribble to the directory of the main
document file. The path argument also can be a result of
path->main-collects-relative.
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 library is non-empty, then
the path argument should not have a suffix.
3.1.4 Spacing
Produces an element that forces a line break.
Like
elem, but line breaks are
suppressed while rendering the content.
Produces an element containing n spaces and style
'hspace.
A string containing the non-breaking space character,
which is equivalent to 'nbsp as an element.
A string containing the non-breaking hyphen character.
A string containing the soft-hyphen character (i.e., a suggestion of
where to hyphenate a word to break it across lines when rendering).
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.
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 .__:
3.1.5 Links
The
decoded
pre-content is hyperlinked to
url. If
style is not supplied, then
underline? determines how the link is rendered.
Generates a literal hyperlinked URL.
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
setup-plt 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 HTML output, the generated reference is the hyperlinked title of
the elements in the section’s title content, except that elements with
the 'aux style property are omitted in the hyperlink
label. If underline? is #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 scribble/manual style shows the
title after the section number. Customize the output (see
Extending and Configuring Scribble Output) by redefining the \BookRef, etc., macros (see
Predefined Latex Macros).
Like
secref, but if the rendered form of the reference starts
with a word (e.g., “section”), then the word is capitalized.
Like
secref, but the link label is the
decoded
pre-content instead of the target section’s name.
Like
secref for the document’s implicit
"top"
tag. 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.
The tag t refers to the content form of
pre-content.
The
decoded
pre-content is hyperlinked to
t,
which is normally defined using
elemtag.
3.1.6 Indexing
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-strings. The
strings (without clean-up) also serve as the text to render in the
index. The
decoded
pre-content is the text to appear
inline as the index target.
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.
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.
Creates a
part-index-decl to be associated with the enclosing
section by
decode. The
words serve as both the keys
and as the rendered forms of the keys within the index.
Produces a part that shows the index the enclosing document. The
optional tag argument is used as the index section’s tag.
3.1.7 Tables of Contents
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.
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.