►Scribble:   The Racket Documentation Tool
►4 Scribbling Documentation
▼4.2 Manual Forms
On this page:
make-id-element
id-to-target-maker
id-to-form-target-maker
annote-exporting-library
with-exporting-libraries
Racket
  top  contents    up   

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    up