4.2.6 Defining Documentation Forms

► |  | Scribble: The Racket Documentation Tool

1 | Getting Started
2 | @ Syntax
3 | High-Level Scribble API
4 | Scribbling Documentation
5 | Literate Programming
6 | Low-Level Scribble API
7 | Running scribble
| Index

► | 4 | Scribbling Documentation

4.1 | Getting Started with Documentation
4.2 | Manual Forms
4.3 | Racket
4.4 | Evaluation and Examples
4.5 | In-Source Documentation
4.6 | BNF Grammars
4.7 | Compatibility Libraries

▼ | 4.2 | Manual Forms

4.2.1 | Typesetting Code
4.2.2 | Documenting Modules
4.2.3 | Documenting Forms, Functions, Structure Types, and Values
4.2.4 | Documenting Classes and Interfaces
4.2.5 | Documenting Signatures
4.2.6 | Defining Documentation Forms
4.2.7 | Various String Forms
4.2.8 | Links
4.2.9 | Indexing
4.2.10 | Bibliography
4.2.11 | Version History
4.2.12 | Miscellaneous
4.2.13 | Index-Entry Descriptions
4.2.14 | Manual Rendering Style

On this page:

make-id-element
id-to-target-maker
id-to-form-target-maker
annote-exporting-library
with-exporting-libraries

Racket
top contents ← prev up next →

#### 4.2.6 Defining Documentation Forms🔗ℹ

(require scribble/manual-def) | package: scribble-lib

The scribble/manual-def module provides utilities for building new documentation forms like defform and defproc. See also boxed-style and add-background-label.

Added in version 1.64 of package scribble-lib.

> > procedure
> > (make-id-element |  | id |  |  |  |
> > |  | str |  |  |  |
> > |  | defn? |  |  |  |
> > | [ | #:space space |  |  |  |
> > |  | #:suffix suffix |  |  |  |
> > |  | #:link-style link-style |  |  |  |
> > |  | #:unlinked-ok? unlinked-ok?]) |  | → |  | content?
> id : identifier?
> str : string?
> defn? : any/c
> space : (or/c #f symbol?) = #f
> suffix : (or/c #f symbol? serializable?) = #f
> link-style : (or/c #f style?) = #f
> unlinked-ok? : any/c = #f

Creates an element that typesets id as code hyperlinked to its definition. The given str is used as the identifier’s typeset form, while id is used for its for-label binding information. If defn? is true, the identifier is a typeset as the defining instance (for use in a definition box, normally).

The space argument indicates a space (in the sense of only-space-in) for the binding. The suffix argument provides an additional suffix on the documentation key, when not #f, and it normally should include space if space is not #f. The suffix might have additional components to, for example, indicate a name syntactically accessible via id, such as through a field-selecting dot notation.

If unlinked-ok? is #false, then if no link target is found based on the for-label binding of id in space, the identifier is typeset as a failed hyperlink. Otherwise, it is typeset without linking.

> > procedure
> > (id-to-target-maker |  | id |
> > |  | dep? |
> > | [ | #:space space |
> > |  | #:suffix suffix]) |
> → (content? (-> tag? content?) . -> . content?)
> id : identifier?
> dep? : any/c
> space : (or/c #f symbol?) = #f
> suffix : (or/c #f symbol? serializable?) = #f

Produces a function to wrap content as a cross-reference link target for the defining instance of the binding indicated by id, space and suffix—which are used as in make-id-element.

The resulting make-target procedure expects content that is used before the resolve pass (e.g., to extract content text) plus a procedure that takes a cross-reference tag and produces a content representing the specific cross reference target. The procedure passed to make-target receives a tag representing the binding, and it typically generates a target-element (possibly a toc-target2-element) using that tag. The generated target-element may also include indexing information using the same tag, and where with-exporting-libraries is used to construct the index description.

> > procedure
> > (id-to-form-target-maker |  | id |
> > |  | dep? |
> > | [ | #:space space |
> > |  | #:suffix suffix]) |
> → (content? (-> tag? content?) . -> . content?)
> id : identifier?
> dep? : any/c
> space : (or/c #f symbol?) = #f
> suffix : (or/c #f symbol? serializable?) = #f

Like id-to-target-maker, but intended for syntactic forms instead than value bindings. In the default manual style, both are style the same.

> > procedure
> > (annote-exporting-library |  | content |  |  |  |
> > | [ | #:format-module-path fmt]) |  | → |  | content?
> content : content?
> fmt : (any/c . -> . string?) = ~s

Wraps content for a defining instance of some identifier to indicate the module path that exports the identifier. This module will be determined via defmodule or declare-exporting in an enclosing section.

> procedure (with-exporting-libraries make-desc) → delayed-index-desc?
> make-desc : (list? . -> . exported-index-desc?)

Creates an index description that incorporates information about relevant modules. Relevant module paths will be determined via defmodule or declare-exporting in an enclosing section and passed to make-desc, whose result will replace the result of with-exporting-libraries for indexing.
top contents ← prev up next →