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
On this page:
9.1 Document Structure
title
section
subsection
subsubsection
subsubsub*section
itemize
item
item?
include-section
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.0.2

 

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.

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.

(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 : 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?

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