6.9 Tag Utilities

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.