3.1 Base Document Format

Functions provided by this library, such as title and italic, might be called from Racket as

(title #:tag "how-to"

"How to Design " (italic "Great") " Programs")

They can also be called with @ notation 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 Racket mode (partly because we have scribble/manual).

3.1.1 Document Structure

The style argument can be a style structure, or it can be one of the following: a #f that corresponds to a “plain” style, a string that is used as a style name, a symbol that is used as a style property, or a list of symbols to be used as style properties. For information on styles, see part. For example, a style of 'toc causes sub-sections to be generated as separate pages in multi-page HTML 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 date argument is propagated to the title-decl structure via a document-date style property. Use "" as date to suppress date rendering in Latex 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.

Note that author+email is not a replacement for author. The author+email function is often used in combination with author.

3.1.2 Blocks

The style argument can be a style, #f to indicate a “plain” style, a string that is used as a style name, or a symbol that is used as a style name. (Note that section and para treat symbols differently as style arguments.)

The style argument is handled the same as para. The 'inset and 'code-inset styles cause the nested flow to be inset compared to surrounding text, with the latter particularly intended for insetting code.

If left? is true, then the note is shown on the opposite as it would normally be shown (which is the left-hand side for HTML output). Beware of colliding with output for a table of contents.

The style argument is handled the same as para. The 'ordered style numbers items, instead of just using a bullet.

(or/c item? block? (listof items/c) (spliceof items/c))

If sep is not #f, it is inserted between every column in the table. Otherwise, the default style places no space between table columns.

Use 'cont as a cell to continue the content of the preceding cell in a row in the space that would otherwise be used for a new cell. A 'cont must not appear as the first cell in a row.

The style argument is handled the same as para.

The strs are not decoded with decode-content, so (verbatim "---") renders with three hyphens instead of an em dash. Beware, however, that reading @verbatim converts @ syntax within the argument, and such reading occurs well before arguments to verbatim are delivered at run-time. To disable simple @ notation within the verbatim argument, verbatim is typically used with |{...}| or similar brackets, like this:

@verbatim|{

Use @bold{---} like this...

}|

which renders as

Use @bold{---} like this...

Even with |{...}|, beware that consistent leading whitespace is removed by the parser; see Alternative Body Syntax for more information.

See also literal.

3.1.3 Text Styles and Content

Beware that @ for a literal call performs some processing before delivering arguments to literal. The literal form can be used with |{...}| or similar brackets to disable @ notation within the literal argument, like this:

@literal|{@bold{---}}|

which renders as

@literal|{@bold{---}}|

See also verbatim.

The path is relative to the current directory, which is set by setup-plt and scribble to the directory of the main document file. The path argument also can be a result of path->main-collects-relative.

The strings in suffixes are filtered to those supported by given renderer, and then the acceptable suffixes are tried in order. The HTML renderer supports ".png", ".gif", and ".svg", while the Latex renderer supports ".png", ".pdf", and ".ps" (but ".ps" works only when converting Latex output to DVI, and ".png" and ".pdf" work only for converting Latex output to PDF).

Note that when the suffixes library is non-empty, then the path argument should not have a suffix.

3.1.4 Spacing

See .__ for an example.

The following example illustrates both ._ and .__:

#lang scribble/base

My name is Mr@._ T@.__ I pity the fool who can't typeset punctuation.

3.1.5 Links

If #:doc module-path is provided, the tag refers to a tag with a prefix determined by module-path. When setup-plt renders documentation, it automatically adds a tag prefix to the document based on the source module. Thus, for example, to refer to a section of the Racket reference, module-path would be '(lib "scribblings/reference/reference.scrbl").

The #:tag-prefixes prefixes argument similarly supports selecting a particular section as determined by a path of tag prefixes. When a #:doc argument is provided, then prefixes should trace a path of tag-prefixed subsections to reach the tag section. When #:doc is not provided, the prefixes path is relative to any enclosing section (i.e., the youngest ancestor that produces a match).

For HTML output, the generated reference is the hyperlinked title of the elements in the section’s title content, except that elements with the 'aux style property are omitted in the hyperlink label. If underline? is #f, then the hyperlink is rendered in HTML without an underline.

For Latex output, the generated reference’s format depends on the document style. By default, only the section number is shown in the reference, but the scribble/manual style shows the title after the section number. Customize the output (see Extending and Configuring Scribble Output) by redefining the \BookRef, etc., macros (see Predefined Latex Macros).

3.1.6 Indexing

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.

3.1.7 Tables of Contents

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 (i.e., in a part structure, not supplied as the style argument to local-table-of-contents), which normally suppresses sub-part entries in a table of contents.