doc improvements: some details on reachability for weak references; module example in insidemz; clarification for 'read-language' related to readtables and #reader

svn: r17905

collects/scribblings/inside/overview.scrbl

@@ -213,7 +213,7 @@ must be extended as follows:
 For a relatively simple extension @filepath{hw.c}, the extension is
 compiled under Unix for 3m with the following three commands:
 
-@commandline{mzc --xform --cc hw.c}
+@commandline{mzc --xform hw.c}
 @commandline{mzc --3m --cc hw.3m.c}
 @commandline{mzc --3m --ld hw.so hw.o}
 
@@ -221,6 +221,50 @@ Some examples in @filepath{collects/mzscheme/examples} work with
 MzScheme3m in this way. A few examples are manually instrumented, in
 which case the @DFlag{xform} step should be skipped.
 
+@subsection{Declaring a Module in an Extension}
+
+To create an extension that behaves as a module, return a symbol from
+@cpp{scheme_module_name}, and have @cpp{scheme_initialize} and
+@cpp{scheme_rename} declare a module using @cpp{scheme_primitive_module}.
+
+For example, the following extension implements a module named
+@scheme[hello] that exports a binding @scheme[greeting]:
+
+@verbatim[#:indent 2]{
+  #include "escheme.h"
+
+  Scheme_Object *scheme_initialize(Scheme_Env *env) {
+    Scheme_Env *mod_env;
+    mod_env = scheme_primitive_module(scheme_intern_symbol("hi"), 
+                                      env);
+    scheme_add_global("greeting", 
+                      scheme_make_utf8_string("hello"), 
+                      mod_env);
+    scheme_finish_primitive_module(mod_env);
+    return scheme_void;
+  }
+
+  Scheme_Object *scheme_reload(Scheme_Env *env) {
+    return scheme_initialize(env); /* Nothing special for reload */
+  }
+
+  Scheme_Object *scheme_module_name() {
+    return scheme_intern_symbol("hi");
+  }
+}
+
+This extension could be compiled for 3m on Mac OS X for i386, for
+example, using the following sequence of @exec{mzc} commands:
+
+@commandline{mzc --xform hi.c}
+@commandline{mzc --3m --cc hi.3m.c}
+@commandline{mkdir -p compiled/native/i386-macosx/3m}
+@commandline{mzc --3m --ld compiled/native/i386-macosx/3m/hi_ss.dylib hi_3m.o}
+
+The resulting module can be loaded with
+
+@schemeblock[(require "hi.ss")]
+
 @; ----------------------------------------------------------------------
 
 @section[#:tag "embedding"]{Embedding MzScheme into a Program}

collects/scribblings/reference/eval-model.scrbl

@@ -366,6 +366,16 @@ via a @tech{weak reference}, then the object can be reclaimed, and the
 @tech{weak reference} is replaced by a different @tech{value}
 (typically @scheme[#f]).
 
+As a special case, a @tech{fixnum} is always considered reachable by
+the garbage collector. Many other values are always reachable due to
+the way they are implemented and used: A @tech{character} in the
+Latin-1 range is always reachable, because @scheme[equal?] Latin-1
+characters are always @scheme[eq?], and all of the Latin-1 characters
+are referenced by an internal module. Similarly, @scheme[null],
+@scheme[#t], @scheme[#f], @scheme[eof], and @|void-const| and are
+always reachable. Values produced by @scheme[quote] remain reachable
+when the @scheme[quote] expression itself is reachable.
+
 @;------------------------------------------------------------------------
 @section{Procedure Applications and Local Variables}
 

collects/scribblings/reference/mpairs.scrbl

@@ -19,7 +19,7 @@ instead created with mutable pairs.
 @defproc[(mpair? [v any/c]) boolean?]{Returns @scheme[#t] if @scheme[v] is
 a mutable pair, @scheme[#f] otherwise.}
 
-@defproc[(mcons [a any/c] [d any/c]) pair?]{Returns a mutable pair whose first
+@defproc[(mcons [a any/c] [d any/c]) pair?]{Returns a newly allocated mutable pair whose first
 element is @scheme[a] and second element is @scheme[d].}
 
 @defproc[(mcar [p mpair?]) any/c]{Returns the first element of the

collects/scribblings/reference/pairs.scrbl

@@ -107,7 +107,7 @@ the empty list, @scheme[#f] otherwise.
 (null? (cdr (list 1)))
 ]}
 
-@defproc[(cons [a any/c] [d any/c]) pair?]{Returns a pair whose first
+@defproc[(cons [a any/c] [d any/c]) pair?]{Returns a newly allocated pair whose first
 element is @scheme[a] and second element is @scheme[d].
 @mz-examples[
 (cons 1 2)

collects/scribblings/reference/read.scrbl

@@ -114,14 +114,21 @@ soon as a @tech{reader language} (or its absence) is determined.
 
 A @deftech{reader language} is specified by @litchar{#lang} or
 @litchar{#!} (see @secref["parse-reader"]) at the beginning of the
-input, though possibly after comment forms. Instead of dispatching to
-a @schemeidfont{read} or @schemeidfont{read-syntax} form as
-@scheme[read] and @scheme[read-syntax] do, @scheme[read-language]
-dispatches to a @schemeidfont{get-info} function (if any) exported by
-the same module. The result of the @schemeidfont{get-info} function is
-the result of @scheme[read-language] if it is a function of two
-arguments; if @schemeidfont{get-info} produces any other kind of
-result, the @exnraise[exn:fail:contract].
+input, though possibly after comment forms. The default
+@tech{readtable} is used by @scheme[read-language] (instead of the
+value of @scheme[current-readtable]), and @litchar{#reader} forms
+(which might produce comments) are not allowed before @litchar{#lang}
+or @litchar{#!}.
+
+When it finds a @litchar{#lang} or @litchar{#!} specification, instead
+of dispatching to a @schemeidfont{read} or @schemeidfont{read-syntax}
+form as @scheme[read] and @scheme[read-syntax] do,
+@scheme[read-language] dispatches to a @schemeidfont{get-info}
+function (if any) exported by the same module. The result of the
+@schemeidfont{get-info} function is the result of
+@scheme[read-language] if it is a function of two arguments; if
+@schemeidfont{get-info} produces any other kind of result, the
+@exnraise[exn:fail:contract].
 
 The function produced by @schemeidfont{get-info} reflects information
 about the expected syntax of the input stream. The first argument to the

collects/scribblings/reference/readtables.scrbl

@@ -5,7 +5,7 @@
 @title[#:style 'toc]{Reader Extension}
 
 Scheme's reader can be extended in three ways: through a reader-macro
-procedure in a readtable (see @secref["readtables"]), through a
+procedure in a @tech{readtable} (see @secref["readtables"]), through a
 @litchar{#reader} form (see @secref["parse-reader"]), or through a
 custom-port byte reader that returns a ``special'' result procedure
 (see @secref["customport"]). All three kinds of @deftech{reader

collects/scribblings/reference/vectors.scrbl

@@ -36,7 +36,7 @@ initialized to contain @scheme[v].}
 
 @defproc[(vector [v any/c] ...) vector?]{
 
-Returns a mutable vector with as many slots as provided @scheme[v]s,
+Returns a newly allocated mutable vector with as many slots as provided @scheme[v]s,
 where the slots are initialized to contain the given @scheme[v]s in
 order.}
 
@@ -44,7 +44,7 @@ order.}
 @defproc[(vector-immutable [v any/c] ...) (and/c vector?
                                                  immutable?)]{
 
-Returns an immutable vector with as many slots as provided
+Returns a newly allocated immutable vector with as many slots as provided
 @scheme[v]s, where the slots are contain the given @scheme[v]s in
 order.}