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
| |||||||||||||||||||||||||||||||||||
tag-prefix : (or/c false/c string? module-path?) = #f | |||||||||||||||||||||||||||||||||||
style : any/c = #f | |||||||||||||||||||||||||||||||||||
pre-content : any/c |
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.
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.
| ||||||||||||||||||||||||||||
tag-prefix : (or/c false/c string? module-path?) = #f | ||||||||||||||||||||||||||||
style : any/c = #f | ||||||||||||||||||||||||||||
pre-content : any/c |
Like title, but generates a part-start of depth 0 to be by decode or decode-part.
| ||||||||||||||||||||||||||||
tag-prefix : (or/c false/c string? module-path?) = #f | ||||||||||||||||||||||||||||
style : any/c = #f | ||||||||||||||||||||||||||||
pre-content : any/c |
Like section, but generates a part-start of depth 1.
| ||||||||||||||||||||||||||||
tag-prefix : (or/c false/c string? module-path?) = #f | ||||||||||||||||||||||||||||
style : any/c = #f | ||||||||||||||||||||||||||||
pre-content : any/c |
Like section, but generates a part-start of depth 2.
| ||||||||||||||||||||||||||||
tag-prefix : (or/c false/c string? module-path?) = #f | ||||||||||||||||||||||||||||
style : any/c = #f | ||||||||||||||||||||||||||||
pre-content : any/c |
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).
(itemize itm ) → itemization? |
itm : (or/c whitespace? an-item?) |
Constructs an itemization given a sequence of items constructed by item. Whitespace strings among the itms are ignored.
pre-flow : any/c |
Creates an item for use with itemize. The decoded pre-flow (i.e., parsed with decode-flow) is the item content.
v : any/c |
Returns #t if v is an item produced by item, #f otherwise.
(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.
(module-path-prefix->string mod-path) → string? |
mod-path : module-path? |
Converts a module path to a string by resolving it to a path, and using path->main-collects-relative.
9.2 Text Styles
pre-content : any/c |
Wraps the decoded pre-content as an element with style #f.
pre-content : any/c |
Like elem, but creates an aux-element.
pre-content : any/c |
Like elem, but with style 'italic
pre-content : any/c |
Like elem, but with style 'bold
pre-content : any/c |
Like elem, but with style 'tt
pre-content : any/c |
Like elem, but with style 'subscript
(superscript pre-content ) → element? |
pre-content : any/c |
Like elem, but with style 'superscript
n : nonnegative-exact-integer? |
Produces an element containing n spaces and style 'hspace.
(span-class style-name pre-content ) → element? |
style-name : string? |
pre-content : any/c |
Wraps the decoded pre-content as an element with style style-name.
9.3 Indexing
(index words pre-content ) → index-element? |
pre-content : any/c |
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.
(index* words word-contents pre-content ) → index-element? |
pre-content : any/c |
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.
(as-index pre-content ) → index-element? |
pre-content : any/c |
Like index, but the word to index is determined by applying content->string on the decoded pre-content.
(section-index word ) → part-index-decl? |
word : string? |
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.
(index-section [#:tag tag]) → part? |
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
(table-of-contents) → delayed-flow-element? |
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.
(local-table-of-contents) → delayed-flow-element? |
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.