doc require/provide transformers and pretty-print

svn: r7820

collects/scheme/provide-transform.ss

@@ -10,7 +10,7 @@
   (#%provide expand-export
              make-provide-transformer prop:provide-transformer provide-transformer?
              ;; the export struct type:
-             export make-export export?
+             export struct:export make-export export?
              export-local-id export-out-sym export-orig-stx export-protect? export-mode)
   
   (define-struct* export (local-id out-sym mode protect? orig-stx)

collects/scheme/require-transform.ss

@@ -11,10 +11,10 @@
   (#%provide expand-import
              make-require-transformer prop:require-transformer require-transformer?
              ;; the import struct type:
-             import make-import import?
+             import struct:import make-import import?
              import-local-id import-src-sym import-src-mod-path import-orig-stx import-mode import-req-mode
              ;; the import-source struct type:
-             import-source make-import-source import-source?
+             import-source struct:import-source make-import-source import-source?
              import-source-mod-path-stx import-source-mode)
   
   (define-struct* import (local-id src-sym src-mod-path mode req-mode orig-stx)

collects/scribblings/reference/data.scrbl

@@ -171,7 +171,7 @@ for each pair of keywords is the same as using
 @scheme[keyword->string] and @scheme[string<?].}
 
 @; ----------------------------------------------------------------------
-@include-section["pairs-scrbl.scrbl"]
+@include-section["pairs.scrbl"]
 
 @; ------------------------------------------------------------
 @section[#:tag "vectors"]{Vectors}

collects/scribblings/reference/file-ports.scrbl

@@ -58,8 +58,8 @@ otherwise available for garbage collection (see
 @secref["gc-model"]); a @tech{will} could be associated input port
 to close it more automatically (see @secref["willexecutor"]).
 
-A @tech{path} value that is the expanded version of @scheme[path] is
-used as the name of the opened port.}
+A @tech{path} value that is the @tech{cleanse}d version of
+@scheme[path] is used as the name of the opened port.}
 
 @defproc[(open-output-file [path path-string?]
                            [#:mode mode-flag (one-of/c 'binary 'text) 'binary]
@@ -126,8 +126,8 @@ otherwise available for garbage collection (see
 @secref["gc-model"]); a @tech{will} could be associated input port
 to close it more automatically (see @secref["willexecutor"]).
 
-A @tech{path} value that is the expanded version of @scheme[path] is
-used as the name of the opened port.}
+A @tech{path} value that is the @tech{cleanse}d version of
+@scheme[path] is used as the name of the opened port.}
 
 @defproc[(open-input-output-file [path path-string?]
                            [#:mode mode-flag (one-of/c 'binary 'text) 'binary]

collects/scribblings/reference/filesystem.scrbl

@@ -312,12 +312,12 @@ A parameter that determines the current directory for resolving
 relative paths.
 
 When the parameter procedure is called to set the current directory,
-the path argument is expanded using @scheme[expand-path], simplified
-using @scheme[simplify-path], and then converted to a directory path
-with @scheme[path->directory-path]; expansion and simplification raise
-an exception if the path is ill-formed. Thus, the current value of
-@scheme[current-directory] is always an expanded, simplified,
-complete, directory path.
+the path argument is @tech{cleanse}d using @scheme[cleanse-path],
+simplified using @scheme[simplify-path], and then converted to a
+directory path with @scheme[path->directory-path]; cleansing and
+simplification raise an exception if the path is ill-formed. Thus, the
+current value of @scheme[current-directory] is always a cleansed,
+simplified, complete, directory path.
 
 The path is not checked for existence when the parameter is set.}
 

collects/scribblings/reference/io.scrbl

@@ -12,5 +12,6 @@
 @include-section["write.scrbl"]
 @include-section["reader.scrbl"]
 @include-section["printer.scrbl"]
+@include-section["pretty-print.scrbl"]
 @include-section["readtables.scrbl"]
 @include-section["custom-write.scrbl"]

collects/scribblings/reference/module-reflect.scrbl

@@ -14,6 +14,10 @@ evaluation (e.g., @scheme[eval]). A filesystem path normally refers to
 a module declaration that was loaded on demand via @scheme[require] or
 other forms.
 
+A @deftech{module path} is a datum that matches the grammar for
+@scheme[_module-path] for @scheme[require]. A module path is relative
+to another module.
+
 @defproc[(resolved-module-path? [v any/c]) boolean?]{
 
 Returns @scheme[#f] if @scheme[v] is a @tech{resolved module path},

collects/scribblings/reference/mz.ss

@@ -21,10 +21,18 @@
   (provide note-lib)
   (define-syntax-rule (note-lib lib)
     (t "The bindings documented in this section are provided by the "
-       (schemeidfont "scheme/list")
+       (schememodname lib)
        " and "
-       (schemeidfont "scheme") 
-       " libraries, but not " (schemeidfont "scheme/base")
+       (schememodname scheme)
+       " libraries, but not " (schememodname scheme/base)
+       "."))
+
+  (provide note-lib-only)
+  (define-syntax-rule (note-lib-only lib)
+    (t "The bindings documented in this section are provided by the "
+       (schememodname lib)
+       " library, not " (schememodname scheme/base)
+       " or " (schememodname scheme)
        "."))
 
   (define (*exnraise s)

collects/scribblings/reference/numbers.scrbl

@@ -1,6 +1,6 @@
 #lang scribble/doc
-@require["mz.ss"]
-@require[(only-in scheme pi)]
+@require["mz.ss"
+         scheme/math]
 
 @title[#:tag "numbers"]{Numbers}
 
@@ -755,3 +755,50 @@ If @scheme[dest-bstr] is provided and it is not of length
 Returns @scheme[#t] if the native encoding of numbers is big-endian
 for the machine running Scheme, @scheme[#f] if the native encoding
 is little-endian.}
+
+@; ------------------------------------------------------------------------
+@section{Extra Constants and Functions}
+
+@declare-exporting[scheme/math scheme]
+@note-lib[scheme/math]
+
+@defthing[euler real?]{
+
+An approximation to Euler's constant: @number->string[euler].}
+
+@defthing[pi real]{
+
+An approximation to the ratio of a circle's circumference to its
+diameter: @number->string[pi].}
+
+@defproc[(sqr [z number?]) number?]{
+
+Returns @scheme[(* z z)].}
+
+@defproc[(sgn [x real?]) (one-of/c 1 0 -1 1.0 0.0 -1.0)]{
+
+Returns the sign of @scheme[x] as either @math{-1}, @math{0}, or
+@math{1}.
+
+@examples[
+(sgn 10)
+(sgn -10.0)
+(sgn 0)
+]}
+
+@defproc[(conjugate [z number?]) number?]{
+
+Returns the complex conjugate of @scheme[z].
+
+@examples[
+(conjugate 1)
+(conjugate 3+4i)
+]}
+
+@defproc[(sinh [z number?]) number?]{
+
+Returns the hyperbolic sine of @scheme[z].}
+
+@defproc[(cosh [z number?]) number?]{
+
+Returns the hyperbolic cosine of @scheme[z].}

collects/scribblings/reference/paths.scrbl

@@ -330,8 +330,8 @@ This procedure does not access the filesystem.}
 
 @defproc[(resolve-path [path path-string?]) path?]{
 
-@tech{Path-expands} @scheme[path] and returns a path that references
-the same file or directory as @scheme[path]. Under @|AllUnix|, if
+@tech{Cleanse}s @scheme[path] and returns a path that references the
+same file or directory as @scheme[path]. Under @|AllUnix|, if
 @scheme[path] is a soft link to another path, then the referenced path
 is returned (this may be a relative path with respect to the directory
 owning @scheme[path]), otherwise @scheme[path] is returned (after

collects/scribblings/reference/pretty-print.scrbl

@@ -0,0 +1,370 @@
+#lang scribble/doc
+@require["mz.ss"
+         scribble/bnf]
+
+@title[#:tag "pretty-print"]{Pretty Printing}
+
+@declare-exporting[scheme/pretty scheme]
+@note-lib[scheme/pretty]
+
+@defproc[(pretty-print [v any/c] [port output-port? (current-output-port)])
+         void?]{
+
+Pretty-prints the value @scheme[v] using the same printed form as
+@scheme[write], but with newlines and whitespace inserted to avoid
+lines longer than @scheme[(pretty-print-columns)], as controlled by
+@scheme[(pretty-print-current-style-table)]. The printed form ends in
+a newline, unless the @scheme[pretty-print-columns] parameter is set
+to @scheme['infinity].
+
+In addition to the parameters defined in this section,
+@scheme[pretty-print] conforms to the @scheme[print-graph],
+@scheme[print-struct], @scheme[print-hash-table],
+@scheme[print-vector-length], and @scheme[print-box] parameters.
+
+The pretty printer also detects structures that have the
+@scheme[prop:custom-write] property and it calls the corresponding
+custom-write procedure. The custom-write procedure can check the
+parameter @scheme[pretty-printing] to cooperate with the
+pretty-printer. Recursive printing to the port automatically uses
+pretty printing, but if the structure has multiple recursively printed
+sub-expressions, a custom-write procedure may need to cooperate more
+to insert explicit newlines. Use @scheme[port-next-location] to
+determine the current output column, use @scheme[pretty-print-columns]
+to determine the target printing width, and use
+@scheme[pretty-print-newline] to insert a newline (so that the
+function in the @scheme[pretty-print-print-line] parameter can be
+called appropriately). Use
+@scheme[make-tentative-pretty-print-output-port] to obtain a port for
+tentative recursive prints (e.g., to check the length of the output).}
+
+
+@defproc[(pretty-display [v any/c][port output-port? (current-output-port)])
+         void?]{
+
+Same as @scheme[pretty-print], but @scheme[v] is printed like
+@scheme[display] instead of like @scheme[write].}
+
+
+@defproc[(pretty-format [v any/c][columns nonnegative-exact-integer? (pretty-print-columns)])
+         string?]{
+
+Like @scheme[pretty-print], except that it returns a string containing
+the pretty-printed value, rather than sending the output to a port.
+
+The optional argument @scheme[columns] argument is used to
+parameterize @scheme[pretty-print-columns].}
+
+
+@defproc[(pretty-print-handler [v any/c]) void?]{
+
+Pretty-prints @scheme[v] if @scheme[v] is not @|void-const|, or prints
+nothing if @scheme[v] is @|void-const|. Pass this procedure to
+@scheme[current-print] to install the pretty printer into the REPL run
+by @scheme[read-eval-print-loop].}
+
+
+@; ----------------------------------------------------------------------
+
+@section{Basic Pretty-Print Options}
+
+@defparam[pretty-print-columns width (or/c positive-exact-integer? (one-of/c 'infinity))]{
+
+A parameter that determines the default width for pretty printing.
+
+If the display width is @scheme['infinity], then pretty-printed output
+is never broken into lines, and a newline is not added to the end of
+the output.}
+
+
+@defparam[pretty-print-depth depth (or/c nonnegative-exact-integer? false/c)]{
+
+Parameter that controls the default depth for recursive pretty
+printing. Printing to @scheme[depth] means that elements nested more
+deeply than @scheme[depth] are replaced with ``...''; in particular, a
+depth of 0 indicates that only simple values are printed. A depth of
+@scheme[#f] (the default) allows printing to arbitrary
+depths.}
+
+
+@defboolparam[pretty-print-exact-as-decimal as-decimal?]{
+
+A parameter that determines how exact non-integers are printed.  If
+the parameter's value is @scheme[#t], then an exact non-integer with a
+decimal representation is printed as a decimal number instead of a
+fraction. The initial value is @scheme[#f].}
+
+@defboolparam[pretty-print-.-symbol-without-bars on?]{
+
+A parameter that controls the printing of the symbol whose print name
+is just a period. If set to a true value, then such a symbol is
+printed as only the period.  If set to a false value, it is printed as
+a period with vertical bars surrounding it.}
+
+
+@defboolparam[pretty-print-show-inexactness show?]{
+
+A parameter that determines how inexact numbers are printed.  If the
+parameter's value is @scheme[#t], then inexact numbers are always
+printed with a leading @litchar{#i}. The initial value is @scheme[#f].}
+
+@; ----------------------------------------------------------------------
+
+@section{Per-Symbol Special Printing}
+
+
+@defboolparam[pretty-print-abbreviate-read-macros abbrev?]{
+
+A parameter that controls whether or not @schemeidfont{quote},
+@schemeidfont{unquote}, @schemeidfont{unquote-splicing}, @|etc| are
+abbreviated with @litchar{'}, @litchar{,}, @litchar[",@"], etc. 
+By default, the abbreviations are enabled.}
+
+
+@defproc[(pretty-print-style-table? [v any/c]) boolean?]{
+
+Returns @scheme[#t] if @scheme[v] is a style table for use with
+@scheme[pretty-print-current-style-table], @scheme[#f] otherwise.}
+
+
+@defparam[pretty-print-current-style-table style-table pretty-print-style-table?]{
+
+A parameter that holds a table of style mappings. See
+@scheme[pretty-print-extend-style-table].}
+
+
+@defproc[(pretty-print-extend-style-table [style-table pretty-print-style-table?]
+                                          [symbol-list (listof symbol?)]
+                                          [like-symbol-list (listof symbol?)])
+         pretty-print-style-table?]{
+
+Creates a new style table by extending an existing
+@scheme[style-table], so that the style mapping for each symbol of
+@scheme[like-symbol-list] in the original table is used for the
+corresponding symbol of @scheme[symbol-list] in the new table. The
+@scheme[symbol-list] and @scheme[like-symbol-list] lists must have the
+same length. The @scheme[style-table] argument can be @scheme[#f], in
+which case with default mappings are used for the original table (see
+below).
+
+The style mapping for a symbol controls the way that whitespace is
+inserted when printing a list that starts with the symbol. In the
+absence of any mapping, when a list is broken across multiple lines,
+each element of the list is printed on its own line, each with the
+same indentation.
+
+The default style mapping includes mappings for the following symbols,
+so that the output follows popular code-formatting rules:
+
+@schemeblock[
+'lambda 'case-lambda
+'define 'define-macro 'define-syntax
+'let letrec 'let*
+'let-syntax 'letrec-syntax
+'let-values 'letrec-values 'let*-values
+'let-syntaxes 'letrec-syntaxes
+'begin 'begin0 'do
+'if 'set! 'set!-values
+'unless 'when
+'cond 'case 'and 'or
+'module
+'syntax-rules 'syntax-case 'letrec-syntaxes+values
+'import 'export 'link
+'require 'require-for-syntax 'require-for-template 'provide
+'public 'private 'override 'rename 'inherit 'field 'init
+'shared 'send 'class 'instantiate 'make-object
+]}
+
+
+@defparam[pretty-print-remap-stylable
+          proc 
+          (any/c . -> . (or/c symbol? false/c))]{
+
+A parameter that controls remapping for styles. This procedure is
+called with each subexpression that appears as the first element in a
+sequence. If it returns a symbol, the style table is used, as if that
+symbol were at the head of the sequence. If it returns @scheme[#f],
+the style table is treated normally.}
+
+
+@; ----------------------------------------------------------------------
+
+@section{Line-Output Hook}
+
+@defproc[(pretty-print-newline [port out-port?][width nonnegative-exact-integer?]) void?]{
+
+Calls the procedure associated with the
+@scheme[pretty-print-print-line] parameter to print a newline to
+@scheme[port], if @scheme[port] is the output port that is redirected
+to the original output port for printing, otherwise a plain newline is
+printed to @scheme[port]. The @scheme[width] argument should be the
+target column width, typically obtained from
+@scheme[pretty-print-columns].}
+
+
+@defparam[pretty-print-print-line proc
+          ((or/c nonnegative-exact-integer? false/c)
+           output-port?
+           nonnegative-exact-integer?
+           (or/c nonnegative-exact-integer? (one-of/c 'infinity))
+           . -> .
+           nonnegative-exact-integer?)]{
+
+A parameter that determines a procedure for printing the newline
+separator between lines of a pretty-printed value. The procedure is
+called with four arguments: a new line number, an output port, the old
+line's length, and the number of destination columns. The return value
+from @scheme[proc] is the number of extra characters it printed at the
+beginning of the new line.
+
+The @scheme[proc] procedure is called before any characters are
+printed with @scheme[0] as the line number and @scheme[0] as the old
+line length; @scheme[proc] is called after the last character for a
+value is printed with @scheme[#f] as the line number and with the
+length of the last line. Whenever the pretty-printer starts a new
+line, @scheme[proc] is called with the new line's number (where the
+first new line is numbered @scheme[1]) and the just-finished line's
+length. The destination-columns argument to @scheme[proc] is always
+the total width of the destination printing area, or
+@scheme['infinity] if pretty-printed values are not broken into lines.
+
+The default @scheme[proc] procedure prints a newline whenever the line
+number is not @scheme[0] and the column count is not
+@scheme['infinity], always returning @scheme[0]. A custom
+@scheme[proc] procedure can be used to print extra text before each
+line of pretty-printed output; the number of characters printed before
+each line should be returned by @scheme[proc] so that the next line
+break can be chosen correctly.
+
+The destination port supplied to @scheme[proc] is generally not the
+port supplied to @scheme[pretty-print] or @scheme[pretty-display] (or
+the current output port), but output to this port is ultimately
+redirected to the port supplied to @scheme[pretty-print] or
+@scheme[pretty-display].}
+
+
+@; ----------------------------------------------------------------------
+
+@section{Value Output Hook}
+
+
+@defparam[pretty-print-size-hook proc
+          (any/c boolean? output-port . -> . (or/c false/c nonnegative-exact-integer?))]{
+
+A parameter that determines a sizing hook for pretty-printing.
+
+The sizing hook is applied to each value to be printed. If the hook
+returns @scheme[#f], then printing is handled internally by the
+pretty-printer. Otherwise, the value should be an integer specifying
+the length of the printed value in characters; the print hook will be
+called to actually print the value (see
+@scheme[pretty-print-print-hook]).
+
+The sizing hook receives three arguments. The first argument is the
+value to print.  The second argument is a Boolean: @scheme[#t] for
+printing like @scheme[display] and @scheme[#f] for printing like
+@scheme[write]. The third argument is the destination port; the port
+is the one supplied to @scheme[pretty-print] or
+@scheme[pretty-display] (or the current output port).  The sizing hook
+may be applied to a single value multiple times during
+pretty-printing.}
+
+
+@defparam[pretty-print-print-hook proc
+          (any/c boolean? output-port . -> . void?)]{
+
+A parameter that determines a print hook for pretty-printing.  The
+print-hook procedure is applied to a value for printing when the
+sizing hook (see @scheme[pretty-print-size-hook]) returns an integer
+size for the value.
+
+The print hook receives three arguments. The first argument is the
+value to print.  The second argument is a boolean: @scheme[#t] for
+printing like @scheme[display] and @scheme[#f] for printing like
+@scheme[write]. The third argument is the destination port; this port
+is generally not the port supplied to @scheme[pretty-print] or
+@scheme[pretty-display] (or the current output port), but output to
+this port is ultimately redirected to the port supplied to
+@scheme[pretty-print] or @scheme[pretty-display].}
+
+
+@defparam[pretty-print-pre-print-hook proc
+          (any/c output-port? . -> . void)]{
+
+A parameter that determines a hook procedure to be called just before
+an object is printed. The hook receives two arguments: the object and
+the output port. The port is the one supplied to @scheme[pretty-print]
+or @scheme[pretty-display] (or the current output port).}
+
+
+@defparam[pretty-print-post-print-hook proc
+          (any/c output-port? . -> . void)]{
+
+A parameter that determines a hook procedure to be called just after
+an object is printed. The hook receives two arguments: the object and
+the output port. The port is the one supplied to @scheme[pretty-print]
+or @scheme[pretty-display] (or the current output port).}
+
+@; ----------------------------------------------------------------------
+
+@section{Additional Custom-Output Support}
+
+@defboolparam[pretty-printing on?]{
+
+A parameter that is set to @scheme[#t] when the pretty printer calls a
+custom-write procedure (see @scheme[prop:custom-write]) for output.
+When pretty printer calls a custom-write procedure merely to detect
+cycles, it sets this parameter to @scheme[#f].}
+
+
+@defproc[(make-tentative-pretty-print-output-port 
+          [out output-port?]
+          [width nonnegative-exact-integer?]
+          [overflow-thunk (-> any)])
+         output-port?]{
+
+Produces an output port that is suitable for recursive pretty printing
+without actually producing output. Use such a port to tentatively
+print when proper output depends on the size of recursive
+prints. Determine the size of the tentative print using
+@scheme[port-count-lines].
+
+The @scheme[out] argument should be a pretty-printing port, such as
+the one supplied to a custom-write procedure when
+@scheme[pretty-printing] is set to true, or another tentative output
+port. The @scheme[width] argument should be a target column width,
+usually obtained from @scheme[pretty-print-column-count], possibly
+decremented to leave room for a terminator. The
+@scheme[overflow-thunk] procedure is called if more than
+@scheme[width] items are printed to the port; it can escape from the
+recursive print through a continuation as a short cut, but
+@scheme[overflow-thunk] can also return, in which case it is called
+every time afterward that additional output is written to the port.
+
+After tentative printing, either accept the result with
+@scheme[tentative-pretty-print-port-transfer] or reject it with
+@scheme[tentative-pretty-print-port-cancel]. Failure to accept or
+cancel properly interferes with graph-structure printing, calls to
+hook procedures, etc.  Explicitly cancel the tentative print even when
+@scheme[overflow-thunk] escapes from a recursive print.}
+
+ 
+@defproc[(tentative-pretty-print-port-transfer 
+          [tentative-out output-port?][orig-out output-port?])
+         void?]{
+
+Causes the data written to @scheme[tentative-out] to be transferred as
+if written to @scheme[orig-out]. The @scheme[tentative-out] argument
+should be a port produced by
+@scheme[make-tentative-pretty-print-output-port], and
+@scheme[orig-out] should be either a pretty-printing port (provided to
+a custom-write procedure) or another tentative output port.}
+
+
+@defproc[(tentative-pretty-print-port-cancel [tentative-out output-port?]) void?]{
+
+Cancels the content of @scheme[tentative-out], which was produced by
+@scheme[make-tentative-pretty-print-output-port]. The main effect of
+canceling is that graph-reference definitions are undone, so that a
+future print of a graph-referenced object includes the defining
+@litchar{#}@nonterm{n}@litchar{=}.}

collects/scribblings/reference/stx-trans.scrbl

@@ -1,5 +1,8 @@
 #lang scribble/doc
-@require["mz.ss"]
+@require[(except-in "mz.ss" import export)
+         (for-syntax scheme/base)
+         (for-label scheme/require-transform
+                    scheme/provide-transform)]
 
 @define[(transform-time) @t{This procedure must be called during the
 dynamic extent of a @tech{syntax transformer} application by the
@@ -409,3 +412,187 @@ mark}. Multiple applications of the same
 @scheme[make-syntax-introducer] result procedure use the same mark,
 and different result procedures use distinct marks.}
 
+@; ----------------------------------------------------------------------
+
+@section[#:tag "require-trans"]{@scheme[require] Transformers}
+
+@declare-exporting[scheme/require-transform]
+@note-lib-only[scheme/require-transform]
+
+A @tech{transformer binding} whose value is a structure with the
+@scheme[prop:require-transformer] property implements a derived
+@scheme[_require-spec] for @scheme[require].
+
+The transformer is called with the syntax object representing its use
+as a @scheme[_require-spec] within a @scheme[require] form, and the
+result must be two lists: a list of @scheme[import]s and a list of
+@scheme[import-source]s.
+
+If the derived form contains a sub-form that is a
+@scheme[_require-spec], then it can call @scheme[expand-import] to
+transform the sub-@scheme[_require-spec] to lists of imports and
+import sources.
+
+
+@defproc[(expand-import [stx syntax?])
+         (values (listof import?) 
+                 (listof import-source?))]{
+
+Expands the given @scheme[_require-spec] to lists of imports and
+import sources.}
+
+
+@defproc[(make-require-transformer [proc (syntax? . ->* . ((listof import?) (listof import-source?)))])
+         require-transformer?]{
+
+Creates a require transformer (i.e., a structure with the
+@scheme[prop:require-transformer] property) using the given procedure
+as the transformer.}
+
+
+@defthing[prop:require-transformer struct-type-property?]{
+
+A property to identify @scheme[require] transformers. The property
+value must be a procedure that takes a syntax object and returns
+import and import-source lists.}
+
+
+@defproc[(require-transformer? [v any/c]) boolean?]{
+
+Returns @scheme[#t] if @scheme[v] has the
+@scheme[prop:require-transformer] property, @scheme[#f] otherwise.}
+
+
+@defstruct[import ([local-id identifier?]
+                   [src-sym symbol?]
+                   [src-mod-path module-path?]
+                   [orig-stx syntax?]
+                   [mode (one-of/c 'run 'syntax 'template 'label)]
+                   [req-mode (one-of/c 'run 'syntax 'template 'label)])]{
+
+A structure representing a single imported identifier:
+
+@itemize{
+
+ @item{@scheme[local-id] --- the identifier to be bound within the
+       importing module.}
+
+ @item{@scheme[src-sym] --- the external name of the binding as
+       exported from its source module.}
+
+ @item{@scheme[src-mod-path] --- a @tech{module path} (relative to the
+       importing module) for the source of the imported binding.}
+
+ @item{@scheme[orig-stx] --- a @tech{syntax object} for the source of
+       the import, used for error reporting.}
+
+ @item{@scheme[mode] --- the @tech{phase level} of the binding in the
+       importing module.}
+
+ @item{@scheme[req-mode] --- the @tech{phase level} shift of the
+       import relative to the exporting module. Since the underlying
+       module system currently allows only for-run @scheme[require]s
+       to import into other @tech{phase levels}, if this value is not
+       @scheme['run], then it must match the @scheme[mode] field's
+       value.}
+
+}}
+
+@defstruct[import-source ([mod-path-stx (and/c syntax?
+                                               (lambda (x)
+                                                 (module-path? (syntax->datum x))))]
+                          [mode (one-of/c 'run 'syntax 'template 'label)])]{
+
+A structure representing an imported module, which must be
+instantiated or visited even if no binding is imported into a module.
+
+@itemize{
+
+ @item{@scheme[mod-path-stx] --- a @tech{module path} (relative
+       to the importing module) for the source of the imported binding.}
+
+ @item{@scheme[mode] --- the @tech{phase level} shift the import.}
+
+}}
+
+
+@; ----------------------------------------------------------------------
+
+@section[#:tag "provide-trans"]{@scheme[provide] Transformers}
+
+@declare-exporting[scheme/provide-transform]
+@note-lib-only[scheme/provide-transform]
+
+A @tech{transformer binding} whose value is a structure with the
+@scheme[prop:provide-transformer] property implements a derived
+@scheme[_provide-spec] for @scheme[provide].
+
+The transformer is called with the syntax object representing its use
+as a @scheme[_provide-spec] within a @scheme[provide] form and a list
+of symbols representing the export modes specified by enclosing
+@scheme[_provide-spec]s. The result must be a list of
+@scheme[export]s.
+
+If the derived form contains a sub-form that is a
+@scheme[_provide-spec], then it can call @scheme[expand-export] to
+transform the sub-@scheme[_provide-spec] to a lists of exports.
+
+
+@defproc[(expand-export [stx syntax?] [modes (listof (one-of/c 'run 'syntax 'label))])
+         (listof export?)]{
+
+Expands the given @scheme[_provide-spec] to a list of exports. The
+@scheme[modes] list controls the expansion of
+sub-@scheme[_provide-specs]; for example, an identifier refers to a
+@tech{phase level} 0 binding unless the @scheme[modes] list specifies
+otherwise. Normally, @scheme[modes] is either empty or contains a
+single symbol.}
+
+
+@defproc[(make-provide-transformer [proc (syntax? (listof (one-of/c 'run 'syntax 'label)) 
+                                          . -> . (listof export?))])
+         provide-transformer?]{
+
+Creates a provide transformer (i.e., a structure with the
+@scheme[prop:provide-transformer] property) using the given procedure
+as the transformer.}
+
+
+@defthing[prop:provide-transformer struct-type-property?]{
+
+A property to identify @scheme[provide] transformers. The property
+value must be a procedure that takes a syntax object and mode list and
+returns an export list.}
+
+
+@defproc[(provide-transformer? [v any/c]) boolean?]{
+
+Returns @scheme[#t] if @scheme[v] has the
+@scheme[prop:provide-transformer] property, @scheme[#f] otherwise.}
+
+
+@defstruct[export ([local-id identifier?]
+                   [out-sym symbol?]
+                   [orig-stx syntax?]
+                   [protect? any/c]
+                   [mode (one-of/c 'run 'syntax 'label)])]{
+
+A structure representing a single imported identifier:
+
+@itemize{
+
+ @item{@scheme[local-id] --- the identifier that is bound within the
+       exporting module.}
+
+ @item{@scheme[out-sym] --- the external name of the binding.}
+
+ @item{@scheme[orig-stx] --- a @tech{syntax object} for the source of
+       the export, used for error reporting.}
+
+ @item{@scheme[protect?] --- indicates whether the identifier should
+       be protected (see @secref["modprotect"]).}
+
+ @item{@scheme[mode] --- the @tech{phase level} of the binding in the
+       exporting module.}
+
+}}

collects/scribblings/reference/syntax.scrbl

@@ -1279,6 +1279,9 @@ pre-defined forms are as follows.
   @scheme[for-syntax-spec], but shifts bindings to the @tech{label
   phase level}.}
 
+ @specsubform[derived-require-spec]{See @secref["require-trans"] for
+ information on expanding the set of @scheme[require-spec] forms.}
+
 A @scheme[module-path] identifies a module, either through a concrete
 name in the form of an identifier, or through an indirect name that
 can trigger automatic loading of the module declaration. Except for
@@ -1452,6 +1455,9 @@ pre-defined forms are as follows.
  @scheme[for-syntax], adjusting each @scheme[provide-spec] to the
  @tech{label phase level}.}
 
+ @specsubform[derived-provide-spec]{See @secref["provide-trans"] for
+ information on expanding the set of @scheme[provide-spec] forms.}
+
 Each export specified within a module must have a distinct symbolic
 export name, though the same binding can be specified with the
 multiple symbolic names.}

collects/scribblings/reference/unix-paths.scrbl

@@ -9,7 +9,7 @@ In @|AllUnix| paths, a @litchar{/} separates elements of the path,
 preceding path, and @litchar{..} as a path element always means the
 parent of the directory indicated by the preceding path. A leading
 @litchar{~} in a path is not treated specially, but
-@scheme[expand-path] can be used to convert a leading @litchar{~}
+@scheme[expand-user-path] can be used to convert a leading @litchar{~}
 element to a user-specific directory. No other character or byte has a
 special meaning within a path. Multiple adjacent @litchar{/} are
 equivalent to a single @litchar{/} (i.e., they act as a single path