► |  | Scribble: The Racket Documentation Tool

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

▼ | 7 | Low-Level Scribble API

7.1 | Scribble Layers
7.2 | @ Reader Internals
7.3 | Structures And Processing
7.4 | Renderers
7.5 | Decoding Text
7.6 | Document Language
7.7 | Document Reader
7.8 | Cross-Reference Utilities
7.9 | Tag Utilities
7.10 | Extending and Configuring Scribble Output

On this page:

make-section-tag
make-module-language-tag
taglet?
doc-prefix
module-path-prefix->string
module-path-index->taglet
intern-taglet

top ← prev up next →

#### 7.9`` Tag Utilities

(require scribble/tag) | package: scribble-lib

The scribble/tag library provides utilities for constructing cross-reference tags. The library is re-exported by scribble/base.

> > procedure
> > (make-section-tag |  | name |  |  |  |
> > | [ | #:doc doc-mod-path |  |  |  |
> > |  | #:tag-prefixes tag-prefixes]) |  | → |  | tag?
> name : string?
> doc-mod-path : (or/c module-path? #f) = #f
> tag-prefixes : (or/c #f (listof string?)) = #f

Forms a tag that refers to a section whose “tag” (as provided by the #:tag argument to section, for example) is name. If doc-mod-path is provided, the tag references a section in the document implemented by doc-mod-path from outside the document. Additional tag prefixes (for intermediate sections, typically) can be provided as tag-prefixes.

> procedure (make-module-language-tag lang) → tag?
> lang : symbol?

Forms a tag that refers to a section that contains defmodulelang for the language lang.

> procedure (taglet? v) → boolean?
> v : any/c

Returns #t if v is a taglet, #f otherwise.

A taglet is a value that can be combined with a symbol via list to form a tag, but that is not a generated-tag. A taglet is therefore useful as a piece of a tag, and specifically as a piece of a tag that can gain a prefix (e.g., to refer to a section of a document from outside the document).

> procedure (doc-prefix mod-path taglet) → taglet?
> mod-path : (or/c #f module-path?)
> taglet : taglet?
> (doc-prefix mod-path extra-prefixes taglet) → taglet?
> mod-path : (or/c #f module-path?)
> extra-prefixes : (or/c #f (listof taglet?))
> taglet : taglet?

Converts part of a cross-reference tag that would work within a document implemented by mod-path to one that works from outside the document, assuming that mod-path is not #f. That is, mod-path is converted to a taglet and added as prefix to an existing taglet.

If extra-prefixes is provided, then its content is added as a extra prefix elements before the prefix for mod-path is added. A #f value for extra-prefixes is equivalent to '().

If mod-path is #f, then taglet is returned without a prefix (except adding extra-prefixes, if provided).

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

> procedure (module-path-index->taglet mpi) → taglet?
> mpi : module-path-index?

Converts a module path index to a taglet—a normalized encoding of the path as an S-expression—that is interned via intern-taglet.

The string form of the taglet is used as prefix in a tag to form cross-references into the document that is implemented by the module referenced by mpi.

> procedure (intern-taglet v) → any/c
> v : any/c

Returns a value that is equal? to v, where multiple calls to intern-taglet for equal? vs produce the same (i.e., eq?) value.
top ← prev up next →