Version: 4.2.1
9 Basic Document Forms
The
scribble/basic library
provides functions and forms that can be used from code written either
in Scheme or with @ expressions.
For example, the title and italic functions might be
called from Scheme as
(title #:tag "how-to" |
"How to Design " (italic "Great") " Programs") |
or with an @ expression 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 Scheme mode (partly because we
have scribble/manual).
9.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.
A style of 'toc causes sub-sections to be generated as
separate pages in multi-page HTML output. A style of 'index
indicates an index section whose body is rendered in two columns for
Latex 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 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).
Returns
#t if
v is an item produced by
item,
#f otherwise.
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
styled-paragraph to show the author(s) of a
document, where each author is represented by an
element. 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, obscuring the e-mail
address slightly to avoid address-harvesting robots.
9.2 Text Styles
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.
Produces an element containing n spaces and style
'hspace.
Wraps the
decoded
pre-content as an element with style
style-name.
9.3 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.
9.4 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, which normally
suppresses sub-part entries in the table of contents.