diff --git a/collects/scribblings/reference/printer.scrbl b/collects/scribblings/reference/printer.scrbl index bf1b2adfd1..c15d0ebbcc 100644 --- a/collects/scribblings/reference/printer.scrbl +++ b/collects/scribblings/reference/printer.scrbl @@ -527,14 +527,26 @@ representation. @tech{Unreadable symbols}, which are typically generated indirectly during expansion and compilation, are saved and restored consistently through @litchar{#~}. -Due to the restrictions on @tech{uninterned} symbols in @litchar{#~}, -do not use @racket[gensym] or @racket[string->uninterned-symbol] to -construct an identifier for a top-level or module binding. Instead, -generate distinct identifiers either with -@racket[generate-temporaries] or by applying the result of -@racket[make-syntax-introducer] to an existing identifier; those -functions will lead to top-level and module bindings with -@tech{unreadable symbol}ic names. +The dynamic nature @tech{uninterned} symbols and their localization +within @litchar{#~} can cause problems when @racket[gensym] or +@racket[string->uninterned-symbol] is used to construct an identifier +for a top-level or module binding (depending on how the identifier and +its references are compiled). To avoid problems, generate distinct +identifiers either with @racket[generate-temporaries] or by applying +the result of @racket[make-syntax-introducer] to an existing +identifier; those functions lead to top-level and module variables +with @tech{unreadable symbol}ic names, and the names are deterministic +as long as expansion is otherwise deterministic. + +Despite the problems inherent with @tech{uninterned} symbols as +variable names, they are partially supported even across multiple +@litchar{#~}s: When compiled code contains a reference to a module-defined +variable whose name is an @tech{uninterned} symbol, the relative +position of the variable among the module's definitions is recorded, +and the reference can be linked back to the definition based on its +position and the characters in its name. This accommodation works only +for variable references in compiled code; it does not work for +@racket[syntax]-quoted identifiers, for example. Finally, a compiled form may contain path literals. Although paths are not normally printed in a way that can be read back in, path literals diff --git a/collects/scribblings/reference/stx-ops.scrbl b/collects/scribblings/reference/stx-ops.scrbl index 6285dae9ba..7c5597009f 100644 --- a/collects/scribblings/reference/stx-ops.scrbl +++ b/collects/scribblings/reference/stx-ops.scrbl @@ -285,9 +285,10 @@ must be a syntax pair that can be flattened into a list. The elements of @racket[stx-pair] can be anything, but string, symbol, keyword (possibly wrapped as syntax), and identifier elements will be embedded in the corresponding generated name, which is useful for debugging -purposes. The generated identifiers are built with interned symbols -(not @racket[gensym]s), so the limitations described with -@racket[current-compile] do not apply.} +purposes. + +The generated identifiers are built with interned symbols (not +@racket[gensym]s); see also @secref["print-compiled"].} @defproc[(identifier-prune-lexical-context [id-stx identifier?]