9 Basic Document Forms

(require scribble/basic)

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

(title  [ #:tag tag             #:tag-prefix tag-prefix             #:style style             #:version vers]             pre-content ...+)   →   title-decl?

tag : (or/c false/c string?) = #f

tag-prefix : (or/c false/c string? module-path?) = #f

style : any/c = #f

vers : (or/c string? false/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. 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.

(section  [ #:tag tag             #:tag-prefix tag-prefix             #:style style]             pre-content ...+)   →   part-start?

tag : (or/c false/c string?) = #f

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.

(subsection  [ #:tag tag             #:tag-prefix tag-prefix             #:style style]             pre-content ...+)   →   part-start?

tag : (or/c false/c string?) = #f

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.

(subsubsection  [ #:tag tag             #:tag-prefix tag-prefix             #:style style]             pre-content ...+)   →   part-start?

tag : (or/c false/c string?) = #f

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.

(subsubsub*section  [ #:tag tag             #:tag-prefix tag-prefix             #:style style]             pre-content ...+)   →   paragraph?

tag : (or/c false/c string?) = #f

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.

(item pre-flow ...) → item?

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.

(item? v) → boolean?

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.

(author auth ...) → block?

auth : any/c

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.

(author+email author email) → element?

author : elem

email : string?

Combines an author name with an e-mail address, obscuring the e-mail address slightly to avoid address-harvesting robots.

(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

(elem pre-content ...) → element?

pre-content : any/c

Wraps the decoded pre-content as an element with style #f.

(aux-elem pre-content ...) → element?

pre-content : any/c

Like elem, but creates an aux-element.

(italic pre-content ...) → element?

pre-content : any/c

Like elem, but with style 'italic

(bold pre-content ...) → element?

pre-content : any/c

Like elem, but with style 'bold

(tt pre-content ...) → element?

pre-content : any/c

Like elem, but with style 'tt

(subscript pre-content ...) → element?

pre-content : any/c

Like elem, but with style 'subscript

(superscript pre-content ...) → element?

pre-content : any/c

Like elem, but with style 'superscript

(hspace n) → element?

n : exact-nonnegative-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?

words : (or/c string? (listof string?))

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?

words : (listof string?)

word-contents : (listof list?)

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?

tag : (or/c false/c string?) = "doc-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

(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.

(local-table-of-contents [#:style style]) → delayed-block?

style : any/c = #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, which normally suppresses sub-part entries in the table of contents.