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

Although the procedures are mostly designed 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.

Examples:

@author{Alice P. Racketeer}

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

Examples:

@author[(author+email "Bob T. Scribbler" "bob@racket-lang.org")]

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. The default style is specified by the output destination (and tends to inset text for HTML output and not inset for Latex output).

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

Use 'cont in cells 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. See table for a list of recognized style names and style properties.

The default style places no space between table columns. If sep is not #f, it is inserted as a new column between every column in the table; the new column’s properties are the same as the preceding column’s, unless sep-properties provides a list of style properties to use. When sep would be placed before a 'cont, a 'cont is inserted, instead.

The column-properties, row-properties, and cell-properties arguments specify style properties for the columns and cells of a table; see table-columns and table-cells for a description of recognized properties. The lists do not contain entries for columns potentially introduced for sep, and when non-empty, they are extended as needed to match the table size determined by cells:

• If the length of column-properties is less than the length of each row in cells, the last item of the list is duplicated to make the list long enough.

• If the length of row-properties is less than the length of cells, the last item of the list is duplicated to make the list long enough.

• If the length of cell-properties is less than the number of rows in cells, then the last element is duplicated to make the list long enough. Each list within cell-properties is treated like a column-properties list—expanded as needed to match the number of columns in each row.

Each element of column-properties or row-properties is either a list of style property values or a non-list element that is wrapped as a list. Similarly, for each list that is an element of cell-properties, the list’s non-list elements are wrapped as nested lists.

If column-properties is non-empty, then its list of property lists is converted into a table-columns style property that is added to the style specified by style—or merged with an existing table-columns style property that matches the column shape of cells. In addition, if either row-properties or cell-properties is non-empty, the property lists of column-properties are merged with the property lists of row-properties and cell-properties. If row-properties or cell-properties is non-empty, the merged lists are converted into a table-cells style property that is added to the style specified by style—or merged with an existing table-cells style property that matches the shape of cells.

If the style lists for column-properties are both merged with cell-properties and converted to table-columns, then style will contain some redundant information. In that case, column-attributes properties will be used from table-columns, while other properties will be used from the merger into table-cells.

Changed in version 1.1 of package scribble-lib: Added the #:column-properties, #:row-properties, and #:cell-properties arguments.
Changed in version 1.12: Changed sep insertion before a 'cont.
Changed in version 1.28: Added sep-properties and made the preceding column’s properties used consistently if not specified.

The string elems 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:

which renders as

while

renders as

Even with brackets like |{...}|, 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

To apply the 'tt style uniformly to all pre-content arguments, use (elem #:style 'tt pre-content ...), instead.

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:

which renders as

See also verbatim.

3.1.4 Images

If path is a relative path, it is relative to the current directory, which is set by raco setup to the directory of the main document file. (In general, however, it’s more reliable to express relative paths using define-runtime-path.) Instead of a path or string, the path argument can be a result of path->main-collects-relative.

The scale argument sets the images scale relative to its default size as determined by the content of path. For HTML output, the resulting image-element is rendered with an img or object (for SVG) tag, and scale adjusts the width and height attributes; a class name or other attributes in style can effectively override that size.

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 list is non-empty, then the path argument should not have a suffix.

Changed in version 1.3 of package scribble-lib: Added the #:style argument.

3.1.5 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.6 Links

If #:doc module-path is provided, the tag refers to a tag with a prefix determined by module-path. When raco setup 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 the result link-element, if ref-style is not #f, then it is attached as a style property and affects the rendering of the link. Alternatively, an enclosing part can have a link-render style that adjusts the rendering style for all links within the part. See link-element for more information about the rendering of section references.

If underline? is #f, then a style is attached to the result link-element so that the hyperlink is rendered in HTML without an underline

In Racket documentation that is rendered to HTML, clicking on a section title normally shows the secref call that is needed to link to the section.

Changed in version 1.25 of package scribble-lib: Added the #:link-render-style argument.

Changed in version 1.25 of package scribble-lib: Added the #:link-render-style argument.

In addition to secref’s arguments, seclink supports a indirect? argument. When indirect? is true, then the section hyperlink’s resolution in HTML is potentially delayed; see 'indirect-link for link-element.

If indirect is not #f, then the link’s resolution in HTML can be delayed, like seclink with #:indirect? #t. The indirect content is prefixed with “the” and suffixed with “documentation” to generate the rendered text of the link. For example:

renders as a hyperlink with the text:

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

3.1.9 Tags

The exports of scribble/tag are all re-exported by scribble/base.