6.9 Tag Utilities

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

▼ | 6 | Low-Level Scribble API

6.1 | Scribble Layers
6.2 | @ Reader Internals
6.3 | Structures And Processing
6.4 | Renderers
6.5 | Decoding Text
6.6 | Document Language
6.7 | Document Reader
6.8 | Cross-Reference Utilities
6.9 | Tag Utilities
6.10 | Blue Boxes Utilities
6.11 | 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
definition-tag->class/ interface-tag
class/ interface-tag->constructor-tag
get-class/ interface-and-method
definition-tag?
class/ interface-tag?
method-tag?
constructor-tag?

top ← prev up next →

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

> procedure (definition-tag->class/interface-tag definition-tag)
> → class/interface-tag?
> definition-tag : definition-tag?

Constructs a tag like definition-tag, except that it matches documentation for the class. If definition-tag doesn’t document a class or interface, this function still returns the tag that the class or interface documentation would have had, as if definition-tag had documented a class or interface.

Added in version 1.11 of package scribble-lib.

> procedure (class/interface-tag->constructor-tag class/interface-tag)
> → constructor-tag?
> class/interface-tag : class/interface-tag?

Constructs a tag like definition-tag, except that it matches documentation for the constructor of the class.

Added in version 1.11 of package scribble-lib.

> > procedure
> > (get-class/interface-and-method method-tag) |  | → |  |
> > symbol? |  | symbol?
> method-tag : method-tag?

Returns the class name and method name (respectively) for the method documented by the docs at method-tag.

Added in version 1.11 of package scribble-lib.

> procedure (definition-tag? v) → boolean?
> v : any/c

Recognizes definition tags. If (definition-tag? v) is #t, then so is (tag? v).

Added in version 1.11 of package scribble-lib.

> procedure (class/interface-tag? v) → boolean?
> v : any/c

Recognizes class or interface tags. If (class/interface-tag? v) is #t, then so is (tag? v).

Added in version 1.11 of package scribble-lib.

> procedure (method-tag? v) → boolean?
> v : any/c

Recognizes method tags. If (method-tag? v) is #t, then so is (tag? v).

Added in version 1.11 of package scribble-lib.

> procedure (constructor-tag? v) → boolean?
> v : any/c

Recognizes class constructor tags. If (constructor-tag? v) is #t, then so is (tag? v).

Added in version 1.11 of package scribble-lib.

top ← prev up next →