▼ |  | Scribble: PLT Documentation Tool

1 | How to Scribble Documentation
2 | Scribble Layers
3 | @-Reader
4 | Structures And Processing
5 | Renderer
6 | Decoding Text
7 | Document Language
8 | Document Reader
9 | Basic Document Forms
10 | Scheme
11 | Manual Forms
12 | Evaluation and Examples
13 | BNF Grammars
14 | Cross-Reference Utilities
15 | Text Preprocessor
| Index

► | 9 | Basic Document Forms

9.1 | Document Structure
9.2 | Text Styles
9.3 | Indexing
9.4 | Tables of Contents

On this page:

9.1`` Document Structure
title
section
subsection
subsubsection
subsubsub*section
itemize
item
item?
include-section
author
author+ email
module-path-prefix->string
9.2`` Text Styles
elem
aux-elem
italic
bold
tt
subscript
superscript
hspace
span-class
9.3`` Indexing
index
index*
as-index
section-index
index-section
9.4`` Tables of Contents
table-of-contents
local-table-of-contents

Version: 4.1.4
top← prev up next →

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

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.

(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 within the index.

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

top← prev up next →