From cbf1d0752ced90216b11d789da4cda05d86a2e7a Mon Sep 17 00:00:00 2001
From: Matthew Flatt <mflatt@racket-lang.org>
Date: Thu, 26 Jul 2007 18:57:19 +0000
Subject: [PATCH] fix many cross-references

svn: r6971
---
 collects/scribblings/reference/bytes.scrbl    | 50 ++++++-------
 collects/scribblings/reference/chars.scrbl    |  5 +-
 .../reference/code-inspectors.scrbl           |  8 +-
 .../scribblings/reference/encodings.scrbl     | 75 +++++++++++++++++++
 collects/scribblings/reference/eval.scrbl     |  8 +-
 collects/scribblings/reference/memory.scrbl   |  4 +-
 .../reference/module-reflect.scrbl            | 10 +--
 .../scribblings/reference/namespaces.scrbl    | 13 ++--
 collects/scribblings/reference/ports.scrbl    | 31 +-------
 collects/scribblings/reference/read.scrbl     |  5 +-
 collects/scribblings/reference/reader.scrbl   |  2 +-
 collects/scribblings/reference/strings.scrbl  | 24 +++---
 .../reference/struct-inspectors.scrbl         | 13 ++++
 .../scribblings/reference/stx-certs.scrbl     |  2 +-
 collects/scribblings/reference/stx-ops.scrbl  | 26 ++++---
 .../scribblings/reference/stx-props.scrbl     |  8 +-
 .../scribblings/reference/stx-trans.scrbl     | 34 ++++-----
 .../scribblings/reference/syntax-model.scrbl  | 66 ++++++++++++----
 collects/scribblings/reference/syntax.scrbl   | 19 ++++-
 19 files changed, 262 insertions(+), 141 deletions(-)
 create mode 100644 collects/scribblings/reference/encodings.scrbl

diff --git a/collects/scribblings/reference/bytes.scrbl b/collects/scribblings/reference/bytes.scrbl
index 1149f0c647..7fdb312851 100644
--- a/collects/scribblings/reference/bytes.scrbl
+++ b/collects/scribblings/reference/bytes.scrbl
@@ -112,17 +112,17 @@ positions are initialized with the given @scheme[b]s.
                       [src-start exact-nonnegative-integer? 0]
                       [src-end exact-nonnegative-integer? (bytes-length src)])
          void?]{
- Changes the bytes of @scheme[dest] from positions
- @scheme[dest-start] (inclusive) to @scheme[dest-end] (exclusive) to
- match the bytes in @scheme[src] from @scheme[src-start]
- (inclusive). The bytes strings @scheme[dest] and @scheme[src] can be the
- same byte string, and in that case the destination region can overlap with
- the source region; the destination bytes after the copy match
- the source bytes from before the copy. If any of
- @scheme[dest-start], @scheme[src-start], or @scheme[src-end]
- are out of range (taking into account the sizes of the bytes strings and
- the source and destination regions), the
- @exnraise[exn:fail:contract].
+
+ Changes the bytes of @scheme[dest] starting at position
+ @scheme[dest-start] to match the bytes in @scheme[src] from
+ @scheme[src-start] (inclusive) to @scheme[src-end] (exclusive). The
+ bytes strings @scheme[dest] and @scheme[src] can be the same byte
+ string, and in that case the destination region can overlap with the
+ source region; the destination bytes after the copy match the source
+ bytes from before the copy. If any of @scheme[dest-start],
+ @scheme[src-start], or @scheme[src-end] are out of range (taking into
+ account the sizes of the bytes strings and the source and destination
+ regions), the @exnraise[exn:fail:contract].
 
 @examples[(define s (bytes 65 112 112 108 101))
           (bytes-copy! s 4 #"y")
@@ -204,14 +204,14 @@ positions are initialized with the given @scheme[b]s.
                               [end exact-nonnegative-integer? (bytes-length bstr)])
          string?]{
  Produces a string by decoding the @scheme[start] to @scheme[end]
- substring of @scheme[bstr] as a UTF-8 encoding of Unicode code points.
- If @scheme[err-char] is not @scheme[#f], then it is used
- for bytes that fall in the range @scheme[#o200] to @scheme[#o377] but
- are not part of a valid encoding sequence. (This is consistent with
- reading characters from a port; see @secref["ports"] for more details.)
- If @scheme[err-char] is @scheme[#f], and if the
- @scheme[start] to @scheme[end] substring of @scheme[bstr] is not a valid
- UTF-8 encoding overall, then the @exnraise[exn:fail:contract].}
+ substring of @scheme[bstr] as a UTF-8 encoding of Unicode code
+ points.  If @scheme[err-char] is not @scheme[#f], then it is used for
+ bytes that fall in the range @scheme[#o200] to @scheme[#o377] but are
+ not part of a valid encoding sequence. (This is consistent with
+ reading characters from a port; see @secref["mz:encodings"] for more
+ details.)  If @scheme[err-char] is @scheme[#f], and if the
+ @scheme[start] to @scheme[end] substring of @scheme[bstr] is not a
+ valid UTF-8 encoding overall, then the @exnraise[exn:fail:contract].}
 
 @defproc[(bytes->string/locale [bstr bytes?]
                                [err-char (or/c false/c char?) #f]
@@ -220,7 +220,7 @@ positions are initialized with the given @scheme[b]s.
          string?]{
  Produces a string by decoding the @scheme[start] to @scheme[end] substring
  of @scheme[bstr] using the current locale's encoding (see also
- @secref["locales"]). If @scheme[err-char] is not
+ @secref["mz:encodings"]). If @scheme[err-char] is not
  @scheme[#f], it is used for each byte in @scheme[bstr] that is not part
  of a valid encoding; if @scheme[err-char] is @scheme[#f], and if the
  @scheme[start] to @scheme[end] substring of @scheme[bstr] is not a valid
@@ -235,7 +235,7 @@ positions are initialized with the given @scheme[b]s.
  of @scheme[bstr] as a Latin-1 encoding of Unicode code points; i.e.,
  each byte is translated directly to a character using
  @scheme[integer->char], so the decoding always succeeds. (See also the
- Latin-1 footnote of @secref["encodings"].)  The @scheme[err-char]
+ Latin-1 footnote of @secref["mz:encodings"].)  The @scheme[err-char]
  argument is ignored, but present for consistency with the other
  operations.}
 
@@ -256,7 +256,7 @@ positions are initialized with the given @scheme[b]s.
          bytes?]{
  Produces a string by encoding the @scheme[start] to @scheme[end] substring
  of @scheme[str] using the current locale's encoding (see also
- @secref["locales"]). If @scheme[err-byte] is not @scheme[#f], it is used
+ @secref["mz:encodings"]). If @scheme[err-byte] is not @scheme[#f], it is used
  for each character in @scheme[str] that cannot be encoded for the
  current locale; if @scheme[err-byte] is @scheme[#f], and if the
  @scheme[start] to @scheme[end] substring of @scheme[str] cannot be encoded,
@@ -272,7 +272,7 @@ positions are initialized with the given @scheme[b]s.
  directly to a byte using @scheme[char->integer]. If @scheme[err-byte] is
  not @scheme[#f], it is used for each character in @scheme[str] whose
  value is greater than @scheme[255]. (See also the Latin-1 footnote of
- @secref["encodings"]. If @scheme[err-byte] is @scheme[#f], and if the
+ @secref["mz:encodings"]. If @scheme[err-byte] is @scheme[#f], and if the
  @scheme[start] to @scheme[end] substring of @scheme[str] has a character
  with a value greater than @scheme[255], then the
  @exnraise[exn:fail:contract].}
@@ -356,12 +356,12 @@ Certain encoding combinations are always available:
    characters; see @secref["mz:ports"].)}
 
  @item{@scheme[(bytes-open-converter "" "UTF-8")] --- converts from
-   the current locale's default encoding (see @secref["mz:locales"])
+   the current locale's default encoding (see @secref["mz:encodings"])
    to UTF-8.}
 
  @item{@scheme[(bytes-open-converter "UTF-8" "")] --- converts from
    UTF-8 to the current locale's default encoding (see
-   @secref["mz:locales"]).}
+   @secref["mz:encodings"]).}
 
  @item{@scheme[(bytes-open-converter "platform-UTF-8" "platform-UTF-16")]
    --- converts UTF-8 to UTF-16 under @|AllUnix|, where each UTF-16
diff --git a/collects/scribblings/reference/chars.scrbl b/collects/scribblings/reference/chars.scrbl
index 5d3f6279be..c3a6283d19 100644
--- a/collects/scribblings/reference/chars.scrbl
+++ b/collects/scribblings/reference/chars.scrbl
@@ -8,8 +8,9 @@
 @guideintro["guide:characters"]{characters}
 
 MzScheme characters range over Unicode scalar values, which includes
-characters whose values range from @scheme[#x0] to @scheme[#x10FFFF],
-but not including @scheme[#xD800] to @scheme[#xDFFF].
+characters whose values range from @schemevalfont{#x0} to
+@schemevalfont{#x10FFFF}, but not including @schemevalfont{#xD800} to
+@schemevalfont{#xDFFF}.
 
 Two characters are @scheme[eqv?] if they correspond to the same scalar
 value. For each scalar value less than 256, character values that are
diff --git a/collects/scribblings/reference/code-inspectors.scrbl b/collects/scribblings/reference/code-inspectors.scrbl
index b8ec4c2af2..51eb52bf2d 100644
--- a/collects/scribblings/reference/code-inspectors.scrbl
+++ b/collects/scribblings/reference/code-inspectors.scrbl
@@ -5,8 +5,8 @@
 
 In the same way that inspectors control access to structure fields
 (see @secref["mz:inspectors"]), inspectors also control access to
-module bindings (see @secref["mz:modules"]). The default inspector for
-module bindings is determined by the @scheme[current-code-inspector]
+@tech{module bindings}. The default inspector for @tech{module
+bindings} is determined by the @scheme[current-code-inspector]
 parameter, instead of the @scheme[current-inspector] parameter.
 
 When a @scheme[module] declaration is evaluated, the value of the
@@ -28,7 +28,7 @@ Control over a module invocation enables
  identifiers exported from the module with @scheme[protect]; and}
 
  @item{access to the module's protected and unexported variables
- within compiled code from @scheme[read] (see @secref["mz:compilation"]).}
+ within compiled code from @scheme[read] (see @scheme[current-compile]).}
 
 }
 
@@ -51,7 +51,7 @@ macro expander prevent any reference to an unexported identifier,
 unless the reference appears within an expression that was generated
 by the module's macros (or, more precisely, a macro from a module
 whose declaration inspector controls the invocation of the
-identifier's module). See @secref["mz:stxprotect"] for further
+identifier's module). See @secref["mz:stxcerts"] for further
 information.
 
 @defparam[current-code-inspector insp inspector?]{
diff --git a/collects/scribblings/reference/encodings.scrbl b/collects/scribblings/reference/encodings.scrbl
new file mode 100644
index 0000000000..1705c65948
--- /dev/null
+++ b/collects/scribblings/reference/encodings.scrbl
@@ -0,0 +1,75 @@
+#reader(lib "docreader.ss" "scribble")
+@require["mz.ss"]
+
+@title[#:tag "mz:encodings"]{Encodings and Locales}
+
+When a port is provided to a character-based operation, such as
+@scheme[read-char] or @scheme[read], the port's bytes are read and
+interpreted as a UTF-8 encoding of characters. Thus, reading a single
+character may require reading multiple bytes, and a procedure like
+@scheme[char-ready?] may need to peek several bytes into the stream to
+determine whether a character is available. In the case of a byte
+stream that does not correspond to a valid UTF-8 encoding, functions
+such as @scheme[read-char] may need to peek one byte ahead in the
+stream to discover that the stream is not a valid encoding.
+
+When an input port produces a sequence of bytes that is not a valid
+UTF-8 encoding in a character-reading context, then bytes that
+constitute an invalid sequence are converted to the character
+@litchar{?}. Specifically, bytes 255 and 254 are always converted to
+@litchar{?}, bytes in the range 192 to 253 produce @litchar{?} when
+they are not followed by bytes that form a valid UTF-8 encoding, and
+bytes in the range 128 to 191 are converted to @litchar{?} when they
+are not part of a valid encoding that was started by a preceding byte
+in the range 192 to 253. To put it another way, when reading a
+sequence of bytes as characters, a minimal set of bytes are changed to
+63 (which is the value that @scheme[(char->integer #\?)] produces) so
+that the entire sequence of bytes is a valid UTF-8 encoding.
+
+See @secref["mz:bytestrings"] for procedures that facilitate
+conversions using UTF-8 or other encodings. See also
+@scheme[reencode-input-port] and @scheme[reencode-output-port] for
+obtaining a UTF-8-based port from one that uses a different encoding
+of characters.
+
+
+A @deftech{locale} captures information about a user's
+culture-specific interpretation of character sequences. In particular,
+a locale determines how strings are ``alphabetized,'' how a lowercase
+character is converted to an uppercase character, and how strings are
+compared without regard to case. String operations such as
+@scheme[string-ci?] are @italic{not} sensitive to the current locale,
+but operations such as @scheme[string-locale-ci?] (see
+@secref["mz:strings"]) produce results consistent with the current
+locale.
+
+A locale also designates a particular encoding of code-point sequences
+into byte sequences. Scheme generally ignores this aspect of the
+locale, with a few notable exceptions: command-line arguments passed
+to Scheme as byte strings are converted to character strings using the
+locale's encoding; command-line strings passed as byte strings to
+other processes (through @scheme[subprocess]) are converted to byte
+strings using the locale's encoding; environment variables are
+converted to and from strings using the locale's encoding; filesystem
+paths are converted to and from strings (for display purposes) using
+the locale's encoding; and, finally, Scheme provides functions such as
+@scheme[string->bytes/locale] to specifically invoke a locale-specific
+encoding.
+
+A Unix user selects a locale by setting environment variables, such as
+@envvar{LC_ALL}. Under Windows and Mac OS X, the operating system
+provides other mechanisms for setting the locale. Within Scheme, the
+current locale can be changed by setting the @scheme[current-locale]
+parameter. The locale name within Scheme is a string, and the
+available locale names depend on the platform and its configuration,
+but the @scheme[""] locale means the current user's default locale;
+under Windows and Mac OS X, the encoding for @scheme[""] is always
+UTF-8, and locale-sensitive operations use the operating system's
+native interface. (In particular, setting the @envvar{LC_ALL} and
+@envvar{LC_CTYPE} environment variables do not affect the locale
+@scheme[""] under Mac OS X. Use @scheme[getenv] and
+@scheme[current-locale] to explicitly install the
+environment-specified locale, if desired.) Setting the current locale
+to @scheme[#f] makes locale-sensitive operations locale-insensitive,
+which means using the Unicode mapping for case operations and using
+UTF-8 for encoding.
diff --git a/collects/scribblings/reference/eval.scrbl b/collects/scribblings/reference/eval.scrbl
index ed1fed1f2e..e14ed7ffa1 100644
--- a/collects/scribblings/reference/eval.scrbl
+++ b/collects/scribblings/reference/eval.scrbl
@@ -96,7 +96,7 @@ If the second argument to the load handler is a symbol, then:
 @itemize{
 
  @item{The @scheme[read-syntax] from the file is additionally
-       @tech{parameterize}d as follows (to provide consistent reading
+       @scheme[parameterize]d as follows (to provide consistent reading
        of module source):
 
        @schemeblock[
@@ -325,8 +325,8 @@ long as the @scheme[read-accept-compiled] parameter is set to
 @scheme[#t]).
 
 When a compiled form contains syntax object constants, the
-@litchar{#~}-marshaled form drops location information and properties
-(@secref["mz:stxprops"]) for the @tech{syntax objects}.
+@litchar{#~}-marshaled form drops source-location information and
+properties (@secref["mz:stxprops"]) for the @tech{syntax objects}.
 
 Compiled code parsed from @litchar{#~} may contain references to
 unexported or protected bindings from a module. At read time, such
@@ -358,7 +358,7 @@ tail position with @scheme[top-level-form].}
 
 @defproc[(compile-syntax [stx syntax?]) compiled-expression?]{
 
-Like @scheme[eval-syntax], but calls the current @tech{compile
+Like @scheme[eval-syntax], but calls the current @tech{compilation
 handler} in tail position with @scheme[stx].}
 
 
diff --git a/collects/scribblings/reference/memory.scrbl b/collects/scribblings/reference/memory.scrbl
index 5fe5a3aeec..e6f6638dd1 100644
--- a/collects/scribblings/reference/memory.scrbl
+++ b/collects/scribblings/reference/memory.scrbl
@@ -14,7 +14,7 @@ is only reachable via weak references, the content of the weak box is
 replaced with @scheme[#f]. A @deftech{weak reference} is a reference
 through a weak box, through a key reference in a weak hash table (see
 @secref["mz:hashtables"]), through a value in an ephemeron where the
-value can be replaced by @scheme[#f] (see @secref["mz:ephemeron"]), or
+value can be replaced by @scheme[#f] (see @secref["mz:ephemerons"]), or
 through a custodian (see @secref["mz:custodians"]).
 
 @defproc[(make-weak-box [v any/c]) weak-box?]{
@@ -34,7 +34,7 @@ collector has proven that the previous content value of
 Returns @scheme[#t] if @scheme[v] is a weak box, @scheme[#f] otherwise.}
 
 @;------------------------------------------------------------------------
-@section[#:tag "mz:ephemeron"]{Ephemerons}
+@section[#:tag "mz:ephemerons"]{Ephemerons}
 
 An @deftech{ephemeron} is similar to a weak box (see
 @secref["mz:weakbox"]), except that
diff --git a/collects/scribblings/reference/module-reflect.scrbl b/collects/scribblings/reference/module-reflect.scrbl
index 3a619e7d3e..482e826a3d 100644
--- a/collects/scribblings/reference/module-reflect.scrbl
+++ b/collects/scribblings/reference/module-reflect.scrbl
@@ -110,10 +110,10 @@ with a message about a dependency cycle.
 
 Module loading is suppressed (i.e., @scheme[#f] is supplied as a third
 argument to the module name resolver) when resolving module paths in
-syntax objects (see @secref["mz:stxobj"]). When a syntax object is
-manipulated, the current namespace might not match the original
-namespace for the syntax object, and the module should not necessarily
-be loaded in the current namespace.
+@tech{syntax objects} (see @secref["mz:stxobj-model"]). When a
+@tech{syntax object} is manipulated, the current namespace might not
+match the original namespace for the syntax object, and the module
+should not necessarily be loaded in the current namespace.
 
 The current module name resolver is called with a single argument by
 @scheme[namespace-attach-module] to notify the resolver that a module
@@ -237,7 +237,7 @@ path index}. The @scheme[path] argument can @scheme[#f] only if
 
 Returns @scheme[#t] if @scheme[v] is a compiled @scheme[module]
 declaration, @scheme[#f] otherwise. See also
-@secref["mz:compilation"].}
+@scheme[current-compile].}
 
 
 @defproc[(module-compiled-name [compiled-module-code compiled-module-expression?])
diff --git a/collects/scribblings/reference/namespaces.scrbl b/collects/scribblings/reference/namespaces.scrbl
index 5766c8b01e..1bbb4a3875 100644
--- a/collects/scribblings/reference/namespaces.scrbl
+++ b/collects/scribblings/reference/namespaces.scrbl
@@ -222,11 +222,12 @@ assignments to the binding via @scheme[set!].}
 @defproc[(namespace-syntax-introduce [stx syntax-object?]) syntax-object?]{
 
 Returns a syntax object like @scheme[stx], except that the current
-namespace's bindings are included in the syntax object's context (see
-@secref["mz:stxscope"]). The additional context is overridden by any
-existing top-level context in the syntax object, or by any existing or
-future module context. See @secref["mz:stxobj"] for more information
-about syntax objects.}
+namespace's bindings are included in the @tech{syntax object}'s
+@tech{lexical information} (see @secref["mz:stxobj-model"]). The
+additional context is overridden by any existing @tech{top-level
+bindings} in the @tech{syntax object}'s @tech{lexical information}, or
+by any existing or future @tech{module bindings} in the @tech{lexical
+information}.}
 
 
 @defproc[(module-provide-protected? [module-path-index (or/c symbol? module-path-index?)]
@@ -245,4 +246,4 @@ indices.
 
 Typically, the arguments to @scheme[module-provide-protected?]
 correspond to the first two elements of a list produced by
-@scheme[identifier-binding] (see @secref["mz:stxscope"]).}
+@scheme[identifier-binding].}
diff --git a/collects/scribblings/reference/ports.scrbl b/collects/scribblings/reference/ports.scrbl
index ce9d4d5daa..c13479953a 100644
--- a/collects/scribblings/reference/ports.scrbl
+++ b/collects/scribblings/reference/ports.scrbl
@@ -4,34 +4,8 @@
 @title[#:tag "mz:ports" #:style 'toc]{Ports}
 
 @deftech{Ports} produce and consume bytes. When a port is provided to
-a character-based operation, such as @scheme[read], the port's bytes
-are read and interpreted as a UTF-8 encoding of characters (see also
-@secref["mz:encodings"]). Thus, reading a single character may require
-reading multiple bytes, and a procedure like @scheme[char-ready?] may
-need to peek several bytes into the stream to determine whether a
-character is available. In the case of a byte stream that does not
-correspond to a valid UTF-8 encoding, functions such as
-@scheme[read-char] may need to peek one byte ahead in the stream to
-discover that the stream is not a valid encoding.
-
-When an input port produces a sequence of bytes that is not a valid
-UTF-8 encoding in a character-reading context, then bytes that
-constitute an invalid sequence are converted to the character
-@litchar{?}. Specifically, bytes 255 and 254 are always converted to
-@litchar{?}, bytes in the range 192 to 253 produce @litchar{?} when
-they are not followed by bytes that form a valid UTF-8 encoding, and
-bytes in the range 128 to 191 are converted to @litchar{?} when they
-are not part of a valid encoding that was started by a preceding byte
-in the range 192 to 253. To put it another way, when reading a
-sequence of bytes as characters, a minimal set of bytes are changed to
-63 (which is the value that @scheme[(char->integer #\?)] produces) so
-that the entire sequence of bytes is a valid UTF-8 encoding.
-
-See @secref["mz:bytestrings"] for procedures that facilitate
-conversions using UTF-8 or other encodings. See also
-@scheme[reencode-input-port] and @scheme[reencode-output-port] for
-obtaining a UTF-8-based port from one that uses a different encoding
-of characters.
+a character-based operation, the port's bytes are decoded; see
+@secref["mz:encodings"].
 
 The global variable @scheme[eof] is bound to the end-of-file value,
 and @scheme[eof-object?] returns @scheme[#t] only when applied to this
@@ -51,6 +25,7 @@ it produces.
 
 @local-table-of-contents[]
 
+@include-section["encodings.scrbl"]
 @include-section["port-procs.scrbl"]
 @include-section["port-buffers.scrbl"]
 @include-section["port-line-counting.scrbl"]
diff --git a/collects/scribblings/reference/read.scrbl b/collects/scribblings/reference/read.scrbl
index 531fa29b78..f5bc1d56ad 100644
--- a/collects/scribblings/reference/read.scrbl
+++ b/collects/scribblings/reference/read.scrbl
@@ -119,7 +119,7 @@ quoting @litchar["\\"] or @litchar["|"] vertical-bar quotes and the
 @litchar{#cs} and @litchar{#ci} prefixes; see
 @secref["mz:parse-symbol"] for more information. While a module is
 loaded, the parameter is set to @scheme[#t] (see
-@secref["mz:modloadhandler"]).}
+@scheme[current-load]).}
 
 @defboolparam[read-square-bracket-as-paren on?]{
 
@@ -141,7 +141,8 @@ A parameter that controls parsing @litchar{#&} input. See
 @defboolparam[read-accept-compiled on?]{
 
 A parameter that controls parsing @litchar{#~} compiled input. See
-@secref["mz:parsing"] for more information.}
+@secref["mz:reader"] and @scheme[current-compile] for more
+information.}
 
 @defboolparam[read-accept-bar-quote on?]{
 
diff --git a/collects/scribblings/reference/reader.scrbl b/collects/scribblings/reference/reader.scrbl
index 7dfab70c47..f0fa4e6553 100644
--- a/collects/scribblings/reference/reader.scrbl
+++ b/collects/scribblings/reference/reader.scrbl
@@ -120,7 +120,7 @@ on the next character or characters in the input stream as follows:
   @dispatch[@litchar["#!/"]]{starts a line comment; see @secref["mz:parse-comment"]}
   @dispatch[@litchar{#`}]{starts a syntax quasiquote; see @secref["mz:parse-quote"]}
   @dispatch[@litchar{#,}]{starts an syntax unquote or splicing unquote; see @secref["mz:parse-quote"]}
-  @dispatch[@litchar["#~"]]{starts compiled code; see @secref["compilation"]}
+  @dispatch[@litchar["#~"]]{starts compiled code; see @scheme[current-compile]}
 
   @dispatch[@cilitchar{#i}]{starts a number; see @secref["mz:parse-number"]}
   @dispatch[@cilitchar{#e}]{starts a number; see @secref["mz:parse-number"]}
diff --git a/collects/scribblings/reference/strings.scrbl b/collects/scribblings/reference/strings.scrbl
index e284da6319..4bbf5682f8 100644
--- a/collects/scribblings/reference/strings.scrbl
+++ b/collects/scribblings/reference/strings.scrbl
@@ -105,17 +105,17 @@ Returns an immutable string with the same content as
                        [src-start exact-nonnegative-integer? 0]
                        [src-end exact-nonnegative-integer? (string-length src)])
          void?]{
- Changes the characters of @scheme[dest] from positions
- @scheme[dest-start] (inclusive) to @scheme[dest-end] (exclusive) to
- match the characters in @scheme[src] from @scheme[src-start]
- (inclusive). The strings @scheme[dest] and @scheme[src] can be the
- same string, and in that case the destination region can overlap with
- the source region; the destination characters after the copy match
- the source characters from before the copy. If any of
- @scheme[dest-start], @scheme[src-start], or @scheme[src-end]
- are out of range (taking into account the sizes of the strings and
- the source and destination regions), the
- @exnraise[exn:fail:contract].
+
+ Changes the characters of @scheme[dest] starting at position
+ @scheme[dest-start] to match the characters in @scheme[src] from
+ @scheme[src-start] (inclusive) to @scheme[src-end] (exclusive). The
+ strings @scheme[dest] and @scheme[src] can be the same string, and in
+ that case the destination region can overlap with the source region;
+ the destination characters after the copy match the source characters
+ from before the copy. If any of @scheme[dest-start],
+ @scheme[src-start], or @scheme[src-end] are out of range (taking into
+ account the sizes of the strings and the source and destination
+ regions), the @exnraise[exn:fail:contract].
 
 @examples[(define s (string #\A #\p #\p #\l #\e))
           (string-copy! s 4 "y")
@@ -310,7 +310,7 @@ allocated string).}
 @defproc[(string-locale=? [str1 string?] [str2 string?] ...+)
  boolean?]{  Like @scheme[string=?], but the strings are compared in a
  locale-specific way, based the value of @scheme[current-locale]. See
- @secref["locales"] for more information on locales.}
+ @secref["mz:encodings"] for more information on locales.}
 
 @defproc[(string-locale<? [str1 string?] [str2 string?] ...+) boolean?]{
  Like @scheme[string<?], but the sort order compares strings in a
diff --git a/collects/scribblings/reference/struct-inspectors.scrbl b/collects/scribblings/reference/struct-inspectors.scrbl
index 8ccbec068a..aced341e84 100644
--- a/collects/scribblings/reference/struct-inspectors.scrbl
+++ b/collects/scribblings/reference/struct-inspectors.scrbl
@@ -127,3 +127,16 @@ type for @scheme[struct-type].  If the type for @scheme[struct-type]
 is not controlled by the current inspector, the
 @exnraise[exn:fail:contract].}
 
+
+
+@defproc[(object-name [v any/c]) any]{
+
+Returns a value for the name of @scheme[v] if @scheme[v] has a name,
+@scheme[#f] otherwise. The argument @scheme[v] can be any value, but
+only (some) procedures, structs, struct types, struct type properties,
+regexp values, and ports have names. The name of a procedure, struct,
+struct type, or struct type property is always a symbol. The name of a
+regexp value is a string, and a byte-regexp value's name is a byte
+string. The name of a port is typically a path or a string, but it can
+be arbitrary. See also @secref["mz:infernames"].}
+
diff --git a/collects/scribblings/reference/stx-certs.scrbl b/collects/scribblings/reference/stx-certs.scrbl
index 139768d64a..cc8a006a3c 100644
--- a/collects/scribblings/reference/stx-certs.scrbl
+++ b/collects/scribblings/reference/stx-certs.scrbl
@@ -32,7 +32,7 @@ object is hidden. (Applying the result of
 keys.) The certificate's mark is applied to both the input and output
 of the syntax transformer, so that it identifies every piece of syntax
 that was introduced by the transformer (see
-@secref["mz:transformer-mode"]). The expander attaches this
+@secref["mz:transformer-model"]). The expander attaches this
 certificate to parts of the transformer's result, depending on the
 shape and properties of the result:
 
diff --git a/collects/scribblings/reference/stx-ops.scrbl b/collects/scribblings/reference/stx-ops.scrbl
index f5c23ef8a2..b781e25bad 100644
--- a/collects/scribblings/reference/stx-ops.scrbl
+++ b/collects/scribblings/reference/stx-ops.scrbl
@@ -13,7 +13,9 @@ otherwise. See also @secref["mz:stxobj-model"].}
 Returns the source for the syntax object @scheme[stx], or @scheme[#f]
 if none is known. The source is represented by an arbitrary value
 (e.g., one passed to @scheme[read-syntax]), but it is typically a file
-path string. See also @secref["mz:compilation"].}
+path string. Source-location information is dropped for a syntax
+object that is marshaled as part of compiled code; see also
+@scheme[current-compile].}
 
 
 @defproc[(syntax-line [stx syntax?]) 
@@ -24,7 +26,8 @@ Returns the line number (positive exact integer) for the start of the
 syntax object in its source, or @scheme[#f] if the line number or
 source is unknown. The result is @scheme[#f] if and only if
 @scheme[(syntax-column stx)] produces @scheme[#f]. See also
-@secref["mz:linecol"] and @secref["mz:compilation"].}
+@secref["mz:linecol"], and see @scheme[syntax-source] for information
+about marshaling compiled syntax objects.}
 
 
 @defproc[(syntax-column [stx syntax?])
@@ -35,7 +38,8 @@ Returns the column number (non-negative exact integer) for the start
 of the syntax object in its source, or @scheme[#f] if the source
 column is unknown. The result is @scheme[#f] if and only if
 @scheme[(syntax-line stx)] produces @scheme[#f]. See also
-@secref["mz:linecol"] and @secref["mz:compilation"].}
+@secref["mz:linecol"], and see @scheme[syntax-source] for information
+about marshaling compiled syntax objects.}
 
 
 @defproc[(syntax-position [stx syntax?])
@@ -44,8 +48,9 @@ column is unknown. The result is @scheme[#f] if and only if
 
 Returns the character position (positive exact integer) for the start
 of the syntax object in its source, or @scheme[#f] if the source
-position is unknown. See also @secref["mz:linecol"] and
-@secref["mz:compilation"].}
+position is unknown. See also @secref["mz:linecol"], and see
+@scheme[syntax-source] for information about marshaling compiled
+syntax objects.}
 
 
 @defproc[(syntax-span [stx syntax?])
@@ -54,7 +59,8 @@ position is unknown. See also @secref["mz:linecol"] and
 
 Returns the span (non-negative exact integer) in characters of the
 syntax object in its source, or @scheme[#f] if the span is
-unknown. See also @secref["mz:compilation"].}
+unknown. See also @scheme[syntax-source] for information about
+marshaling compiled syntax objects.}
 
 
 @defproc[(syntax-original? [stx syntax?]) boolean?]{
@@ -62,9 +68,9 @@ unknown. See also @secref["mz:compilation"].}
 Returns @scheme[#t] if @scheme[stx] has the property that
 @scheme[read-syntax] and @scheme[read-honu-syntax] attach to the
 syntax objects that they generate (see @secref["mz:stxprops"]), and if
-@scheme[stx]'s lexical information does not indicate that the object
-was introduced by a syntax transformer (see
-@secref["mz:stxscope"]). The result is @scheme[#f] otherwise. This
+@scheme[stx]'s @tech{lexical information} does not indicate that the
+object was introduced by a syntax transformer (see
+@secref["mz:stxobj-model"]). The result is @scheme[#f] otherwise. This
 predicate can be used to distinguish syntax objects in an expanded
 expression that were directly present in the original expression, as
 opposed to syntax objects inserted by macros.}
@@ -203,4 +209,4 @@ of @scheme[stx-pair] can be anything, but string, symbol, and
 identifier elements will be embedded in the corresponding generated
 name (useful for debugging purposes). The generated identifiers are
 built with interned symbols (not @scheme[gensym]s), so the limitations
-described in @secref["mz:compilation"] do not apply.}
+described with @scheme[current-compile] do not apply.}
diff --git a/collects/scribblings/reference/stx-props.scrbl b/collects/scribblings/reference/stx-props.scrbl
index 2b74ff59e1..a40b04ccd1 100644
--- a/collects/scribblings/reference/stx-props.scrbl
+++ b/collects/scribblings/reference/stx-props.scrbl
@@ -78,7 +78,7 @@ MzScheme adds properties to expanded syntax (often using
 
  @item{When a reference to an unexported or protected identifier from
  a module is discovered (and the reference is certified; see
- @secref["mz:stxprotect"]), the @scheme['protected] property is added
+ @secref["mz:stxcerts"]), the @scheme['protected] property is added
  to the identifier with a @scheme[#t] value.}
 
  @item{When or @scheme[read-syntax] or @scheme[read-honu-syntax]
@@ -91,9 +91,9 @@ MzScheme adds properties to expanded syntax (often using
 }
 
 See @secref["mz:modinfo"] for information about properties generated
-by the expansion of a module declaration. See @secref["mz:arity"] and
+by the expansion of a module declaration. See @scheme[lambda] and
 @secref["mz:infernames"] for information about properties recognized
-when compiling a procedure. See @secref["mz:compilation"] for
+when compiling a procedure. See @scheme[current-compile] for
 information on properties and byte codes.
 
 @;------------------------------------------------------------------------
@@ -116,7 +116,7 @@ the key @scheme[key], or @scheme[#f] if no value is associated to
 @defproc[(syntax-property-symbol-keys [stx syntax?]) list?]{
 
 Returns a list of all symbols that as keys have associated properties
-in @scheme[stx]. @tech{Uninterned} symbols (see @secref["mz:symbol"])
+in @scheme[stx]. @tech{Uninterned} symbols (see @secref["mz:symbols"])
 are not included in the result list.}
 
 
diff --git a/collects/scribblings/reference/stx-trans.scrbl b/collects/scribblings/reference/stx-trans.scrbl
index 7236f701a6..0c0516cd77 100644
--- a/collects/scribblings/reference/stx-trans.scrbl
+++ b/collects/scribblings/reference/stx-trans.scrbl
@@ -93,14 +93,13 @@ value and @scheme[cons] it onto the current result of
 
 When an identifier in @scheme[stop-ids] is encountered by the expander
 in a subexpression, expansions stops for the subexpression.  If
-@scheme[#%app], @scheme[#%top], or @scheme[#%datum] (see
-@secref["mz:stxspecial"]) appears in @scheme[stop-ids], then
-application, top-level variable reference, and literal data
-expressions without the respective explicit form are not wrapped with
-the explicit form. If @scheme[stop-ids] is @scheme[#f] instead of a
-list, then @scheme[stx] is expanded only as long as the outermost form
-of @scheme[stx] is a macro (i.e., expansion does not proceed to
-sub-expressions).
+@scheme[#%app], @scheme[#%top], or @scheme[#%datum] appears in
+@scheme[stop-ids], then application, top-level variable reference, and
+literal data expressions without the respective explicit form are not
+wrapped with the explicit form. If @scheme[stop-ids] is @scheme[#f]
+instead of a list, then @scheme[stx] is expanded only as long as the
+outermost form of @scheme[stx] is a macro (i.e., expansion does not
+proceed to sub-expressions).
 
 The optional @scheme[intdef-ctx] argument must be either @scheme[#f]
 or the result of @scheme[syntax-local-make-definition-context]. In the
@@ -110,7 +109,7 @@ added to the expansion result (because the expansion might introduce
 bindings or references to internal-definition bindings).
 
 Expansion of @scheme[stx] can use certificates for the expression
-already being expanded (see @secref["mz:stxprotect"]) , and inactive
+already being expanded (see @secref["mz:stxcerts"]) , and inactive
 certificates associated with @scheme[stx] are activated for
 @scheme[stx] (see @secref["mz:stxinactivecerts"]). Furthermore, if the
 transformer is defined within a module (i.e., the current expansion
@@ -248,7 +247,7 @@ if not @scheme[#f]. If @scheme[failure-thunk] is @scheme[false], the
 @exnraise[exn:fail:contract].
 
 Resolving @scheme[id-stx] can use certificates for the expression
-being transformed (see @secref["mz:stxprotect"]) as well as inactive
+being transformed (see @secref["mz:stxcerts"]) as well as inactive
 certificates associated with @scheme[id-stx] (see
 @secref["mz:stxinactivecerts"]). Furthermore, if the transformer is
 defined within a module (i.e., the current transformation was
@@ -367,14 +366,13 @@ procedure accepts one to three arguments: @scheme[_stx] (required),
 procedure's result is a syntax object like @scheme[stx], except that
 it includes the captured certificates as inactive (see
 @secref["mz:stxinactivecerts"]) if @scheme[active?] is @scheme[#f]
-(the default) or active otherwise. If @scheme[key] is supplied and
-not @scheme[#f], it is associated with each captured certificate for
-later use through @scheme[syntax-recertify] (see
-@secref["mz:stxtransfer"]). If @scheme[_intro] is supplied, and if it
-is not @scheme[#f] (the default), then it must be a procedure created
-by @scheme[make-syntax-introducer], in which case the certificate
-applies only to parts of @scheme[stx] that are marked as introduced by
-@scheme[_intro].
+(the default) or active otherwise. If @scheme[key] is supplied and not
+@scheme[#f], it is associated with each captured certificate for later
+use through @scheme[syntax-recertify]. If @scheme[_intro] is supplied,
+and if it is not @scheme[#f] (the default), then it must be a
+procedure created by @scheme[make-syntax-introducer], in which case
+the certificate applies only to parts of @scheme[stx] that are marked
+as introduced by @scheme[_intro].
 
 Supply @scheme[#t] for @scheme[active?] when the syntax to be
 certified can be safely used in any context by any party, and where
diff --git a/collects/scribblings/reference/syntax-model.scrbl b/collects/scribblings/reference/syntax-model.scrbl
index 8a456f0f9e..d597a0c2b3 100644
--- a/collects/scribblings/reference/syntax-model.scrbl
+++ b/collects/scribblings/reference/syntax-model.scrbl
@@ -41,17 +41,17 @@ some are quoted to produce a symbol or a syntax object.
 
 An identifier @deftech{binds} another (i.e., it is a
 @deftech{binding}) when the former is parsed as a @tech{variable} and
-the latter is parsed as a reference to the former.  The
-@deftech{scope} of a binding is the set of source forms to which it
-applies. The @deftech{environment} of a form is the set of bindings
-whose @tech{scope} includes the form. A binding for a sub-expression
-@deftech{shadows} any @tech{bindings} (i.e., it is
-@deftech{shadowing}) in its @tech{environment}, so that uses of an
-@tech{identifier} refer to the @tech{shadowing} @tech{binding}.  A
-@deftech{top-level binding} is a @tech{binding} from a definition at
-the top-level; a @deftech{module binding} is a binding from a
-definition in a module; and a @deftech{local binding} is another other
-kind of binding.
+the latter is parsed as a reference to the former; the latter is
+@deftech{bound}.  The @deftech{scope} of a @tech{binding} is the set
+of source forms to which it applies. The @deftech{environment} of a
+form is the set of bindings whose @tech{scope} includes the form. A
+binding for a sub-expression @deftech{shadows} any @tech{bindings}
+(i.e., it is @deftech{shadowing}) in its @tech{environment}, so that
+uses of an @tech{identifier} refer to the @tech{shadowing}
+@tech{binding}.  A @deftech{top-level binding} is a @tech{binding}
+from a definition at the top-level; a @deftech{module binding} is a
+binding from a definition in a module; and a @deftech{local binding}
+is another other kind of binding.
 
 For example, as a bit of source, the text
 
@@ -525,8 +525,8 @@ properties} such as @scheme['origin]. See @secref["mz:stxprops"] for
 more information.
 
 Finally, the expander uses @tech{syntax certificates} to control the
-way that unexported and protected @tech{module-level bindings} are
-used. See @secref["mz:stxcerts"] for more information on @tech{syntax
+way that unexported and protected @tech{module bindings} are used. See
+@secref["mz:stxcerts"] for more information on @tech{syntax
 certificates}.
 
 The expander's handling of @scheme[letrec-values+syntaxes] is similar
@@ -669,7 +669,7 @@ For expansion purposes, a namespace maps each symbol in each
 
 @itemize{
 
- @item{a particular module-level binding from a particular module}
+ @item{a particular @tech{module binding} from a particular module}
 
  @item{a top-level transformer binding named by the symbol}
 
@@ -752,3 +752,41 @@ x
 (eval:alts x (eval 'x))
 (f)
 ]
+
+@;------------------------------------------------------------------------
+@section[#:tag "mz:infernames"]{Inferred Value Names}
+
+To improve error reporting, names are inferred at compile-time for
+certain kinds of values, such as procedures. For example, evaluating
+the following expression:
+
+@schemeblock[
+(let ([f (lambda () 0)]) (f 1 2 3))
+]
+
+produces an error message because too many arguments are provided to
+the procedure. The error message is able to report @schemeidfont{f} as
+the name of the procedure. In this case, Scheme decides, at
+compile-time, to name as @scheme['f] all procedures created by the
+@scheme[let]-bound @scheme[lambda].
+
+Names are inferred whenever possible for procedures. Names closer to
+an expression take precedence. For example, in
+
+@schemeblock[
+(define my-f
+  (let ([f (lambda () 0)]) f))
+]
+
+the procedure bound to @scheme[my-f] will have the inferred name
+@scheme['f].
+
+When an @scheme['inferred-name] property is attached to a syntax
+object for an expression (see @secref["mz:stxprops"]), the property
+value is used for naming the expression, and it overrides any name
+that was inferred from the expression's context.
+
+When an inferred name is not available, but a source location is
+available, a name is constructed using the source location
+information. Inferred and property-assigned names are also available
+to syntax transformers, via @scheme[syntax-local-name].
diff --git a/collects/scribblings/reference/syntax.scrbl b/collects/scribblings/reference/syntax.scrbl
index a99b521492..84395a0b2e 100644
--- a/collects/scribblings/reference/syntax.scrbl
+++ b/collects/scribblings/reference/syntax.scrbl
@@ -324,6 +324,19 @@ the procedure body.
        (f #:arg 2 1)))
 ]}
 
+When compiling a @scheme[lambda] or @scheme[case-lambda] expression,
+Scheme looks for a @scheme['method-arity-error] property attached to
+the expression (see @secref["mz:stxprops"]). If it is present with a
+true value, and if no case of the procedure accepts zero arguments,
+then the procedure is marked so that an
+@scheme[exn:fail:contract:arity] exception involving the procedure
+will hide the first argument, if one was provided. (Hiding the first
+argument is useful when the procedure implements a method, where the
+first argument is implicit in the original source). The property
+affects only the format of @scheme[exn:fail:contract:arity]
+exceptions, not the result of @scheme[procedure-arity].
+
+
 @defform[(case-lambda [formals body ...+] ...)]{
 
 Produces a procedure. Each @scheme[[forms body ...+]]
@@ -810,11 +823,11 @@ Equivalent to @scheme[(when (not test-expr) expr ...)].
 
 @defform[(set! id expr)]{
 
-If @scheme[id] has a @tech{transformer bounding} to an
+If @scheme[id] has a @tech{transformer binding} to an
 @tech{assignment transformer}, as produced by
 @scheme[make-set!-transformer], then this form is expanded by calling
 the assignment transformer with the full expressions. If @scheme[id]
-has a @tech{transformer bounding} to a @tech{rename transformer} as
+has a @tech{transformer binding} to a @tech{rename transformer} as
 produced by @scheme[make-rename-transformer], then this form is
 expanded by replacing @scheme[id] with the one provided to
 @scheme[make-rename-transformer].
@@ -1131,7 +1144,7 @@ and @secref["mz:mod-parse"]).
                              (prefix provide-spec prefix-id)])]{
 
 Declares exports from a module. A @scheme[provide] form must appear in
-a @tech{module context} or a @tech{module-begin} context.
+a @tech{module context} or a @tech{module-begin context}.
 
 A @scheme[provide-spec] indicates one or more bindings to provide,
 specifying for each an export symbol that can be different from