some doc clarifications and hyperlinks

svn: r12682

collects/scribblings/reference/bytes.scrbl

@@ -335,7 +335,7 @@ string.
 @defproc[(bytes-open-converter [from-name string?][to-name string?])
          bytes-converter?]{
 
-Produces a string converter to go from the encoding named by
+Produces a @deftech{byte converter} to go from the encoding named by
 @scheme[from-name] to the encoding named by @scheme[to-name]. If the
 requested conversion pair is not available, @scheme[#f] is returned
 instead of a converter.
@@ -534,8 +534,8 @@ The result of @scheme[bytes-convert-end] is two values:
 
 @defproc[(bytes-converter? [v any/c]) boolean?]{
 
-Returns @scheme[#t] if @scheme[v] is a byte converter produced by
+Returns @scheme[#t] if @scheme[v] is a @tech{byte converter} produced
-@scheme[bytes-open-converter], @scheme[#f] otherwise.}
+by @scheme[bytes-open-converter], @scheme[#f] otherwise.}
 
 
 @defproc[(locale-string-encoding) any]{

collects/scribblings/reference/custodians.scrbl

@@ -1,6 +1,8 @@
 #lang scribble/doc
 @(require "mz.ss")
 
+@(define eventspaces @tech[#:doc '(lib "scribblings/gui/gui.scrbl")]{eventspaces})
+
 @title[#:tag "custodians"]{Custodians}
 
 See @secref["custodian-model"] for basic information on the PLT
@@ -22,8 +24,13 @@ automatically directed to shut down its managed values as well.}
 
 @defproc[(custodian-shutdown-all [cust custodian?]) void?]{
 
-Closes all open ports and closes all active TCP listeners and UDP
+@margin-note{In MrEd, @|eventspaces| managed by @scheme[cust] are also
-sockets that are managed by @scheme[cust]. It also removes
+             shut down.}
+
+Closes all @tech{file-stream ports}, @tech{TCP ports}, @tech{TCP
+listeners}, and @tech{UDP sockets} that are managed by @scheme[cust]
+(and its subordinates), and empties all @tech{custodian box}es
+associated with @scheme[cust] (and its subordinates). It also removes
 @scheme[cust] (and its subordinates) as managers of all threads; when
 a thread has no managers, it is killed (or suspended; see
 @scheme[thread/suspend-to-kill]) If the current thread is to be
@@ -33,18 +40,20 @@ thread.}
 
 @defparam[current-custodian cust custodian?]{
 
+@margin-note{In MrEd, custodians also manage @|eventspaces|.}
+
 A parameter that determines a custodian that assumes responsibility
-for newly created threads, ports, TCP listeners, UDP sockets, and
+for newly created threads, @tech{file-stream ports}, TCP ports,
-byte converters.}
+@tech{TCP listeners}, @tech{UDP sockets}, and @tech{byte converters}.}
 
 
 @defproc[(custodian-managed-list [cust custodian?][super custodian?]) list?]{
 
-Returns a list of immediately managed objects and subordinate
+Returns a list of immediately managed objects (not including
-custodians for @scheme[cust], where @scheme[cust] is itself
+@tech{custodian box}es) and subordinate custodians for @scheme[cust],
-subordinate to @scheme[super] (directly or indirectly). If
+where @scheme[cust] is itself subordinate to @scheme[super] (directly
-@scheme[cust] is not strictly subordinate to @scheme[super], the
+or indirectly). If @scheme[cust] is not strictly subordinate to
-@exnraise[exn:fail:contract].}
+@scheme[super], the @exnraise[exn:fail:contract].}
 
 @defproc[(custodian-memory-accounting-available?) boolean?]{
 
@@ -81,6 +90,11 @@ after garbage collection (see @secref["gc-model"]) where
 @scheme[limit-cust] owns more than @scheme[limit-amt] bytes, then
 @scheme[stop-cust] is shut down.
 
+@margin-note{A custodian's limit is checked only after a garbage
+             collection, except that it may also be checked during
+             certain large allocations that are individually larger
+             than the custodian's limit.}
+
 For reliable shutdown, @scheme[limit-amt] for
 @scheme[custodian-limit-memory] must be much lower than the total
 amount of memory available (minus the size of memory that is
@@ -93,7 +107,7 @@ immediate allocations can be rejected with an
 
 @defproc[(make-custodian-box [cust custodian?][v any/c]) custodian-box?]{
 
-Returns a @deftech{custodian box} that contains @scheme[v] as long as
+Returns a @tech{custodian box} that contains @scheme[v] as long as
 @scheme[cust] has not been shut down.}
 
 @defproc[(custodian-box? [v any/c]) boolean?]{Returns @scheme[#t] if

collects/scribblings/reference/eval-model.scrbl

@@ -744,12 +744,12 @@ outermost frame of the continuation for any new thread.
 
 @margin-note/ref{See @secref["custodians"] for custodian functions.}
 
-A @deftech{custodian} manages a collection of threads, file-stream
+A @deftech{custodian} manages a collection of threads,
-ports, TCP ports, TCP listeners, UDP sockets, and byte converters.
+@tech{file-stream ports}, TCP ports, @tech{TCP listeners}, @tech{UDP
-Whenever a thread, file-stream port, TCP port, TCP listener, or UDP
+sockets}, and @tech{byte converters}.  Whenever a thread, etc. is
-socket is created, it is placed under the management of the
+created, it is placed under the management of the @deftech{current
-@deftech{current custodian} as determined by the
+custodian} as determined by the @scheme[current-custodian]
-@scheme[current-custodian] @tech{parameter}.
+@tech{parameter}.
 
 @margin-note{In MrEd, custodians also manage eventspaces.}
 
@@ -785,7 +785,7 @@ collected, at which point its subordinates become immediately
 subordinate to the collected custodian's superordinate custodian.
 
 In addition to the other entities managed by a custodian, a
-@defterm{custodian box} created with @scheme[make-custodian-box]
+@deftech{custodian box} created with @scheme[make-custodian-box]
 strongly holds onto a value placed in the box until the box's
 custodian is shut down. The custodian only weakly retains the box
 itself, however (so the box and its content can be collected if there

collects/scribblings/reference/networking.scrbl

@@ -51,11 +51,11 @@ supported or IPv6 sockets are not configurable, then the IPv6
 addresses are ignored; otherwise, each IPv6 listener accepts only IPv6
 connections.)
 
-The return value of @scheme[tcp-listen] is a TCP listener value. This
+The return value of @scheme[tcp-listen] is a @deftech{TCP
-value can be used in future calls to @scheme[tcp-accept],
+listener}. This value can be used in future calls to
-@scheme[tcp-accept-ready?], and @scheme[tcp-close].  Each new TCP
+@scheme[tcp-accept], @scheme[tcp-accept-ready?], and
-listener value is placed into the management of the current custodian
+@scheme[tcp-close].  Each new TCP listener value is placed into the
-(see @secref["custodians"]).
+management of the current custodian (see @secref["custodians"]).
 
 If the server cannot be started by @scheme[tcp-listen], the
 @exnraise[exn:fail:network].}
@@ -137,8 +137,7 @@ not both.}
          (values input-port? output-port?)]{
 
 Accepts a client connection for the server associated with
-@scheme[listener], which is a TCP listener value returned by
+@scheme[listener]. If no client connection is waiting on the
-@scheme[tcp-listen]. If no client connection is waiting on the
 listening port, the call to @scheme[tcp-accept] will block. (See also
 @scheme[tcp-accept-ready?].)
 
@@ -168,8 +167,7 @@ raised, but not both.}
 @defproc[(tcp-accept-ready? [listener tcp-listener?]) boolean?]{
 
 Tests whether an unaccepted client has connected to the server
-associated with @scheme[listener]. The @scheme[listener] argument is a
+associated with @scheme[listener]. If a client is
-TCP listener value returned by @scheme[tcp-listen]. If a client is
 waiting, the return value is @scheme[#t], otherwise it is
 @scheme[#f]. A client is accepted with the @scheme[tcp-accept]
 procedure, which returns ports for communicating with the client and
@@ -180,10 +178,9 @@ If the listener has been closed, the @exnraise[exn:fail:network].}
 
 @defproc[(tcp-close [listener tcp-listener?]) void?]{
 
-Shuts down the server associated with @scheme[listener]. The
+Shuts down the server associated with @scheme[listener]. All
-@scheme[listener] argument is a TCP listener value returned by
+unaccepted clients receive an end-of-file from the server; connections
-@scheme[tcp-listen]. All unaccepted clients receive an end-of-file
+to accepted clients are unaffected.
-from the server; connections to accepted clients are unaffected.
 
 If the listener has already been closed, the @exnraise[exn:fail:network].
 
@@ -195,7 +192,7 @@ explanation of the @tt{TIME_WAIT} TCP state.}
 
 @defproc[(tcp-listener? [v any/c]) boolean?]{
 
-Returns @scheme[#t] if @scheme[v] is a TCP listener value created by
+Returns @scheme[#t] if @scheme[v] is a @tech{TCP listener} created by
 @scheme[tcp-listen], @scheme[#f] otherwise.}
 
 
@@ -220,7 +217,7 @@ closed.
 
 The TCP protocol does not include a ``no longer reading'' state on
 connections, so @scheme[tcp-abandon-port] is equivalent to
-@scheme[close-input-port] on input TCP ports.}
+@scheme[close-input-port] on input @tech{TCP ports}.}
 
 
 @defproc[(tcp-addresses [tcp-port tcp-port?]
@@ -231,7 +228,7 @@ connections, so @scheme[tcp-abandon-port] is equivalent to
 
 Returns two strings when @scheme[port-numbers?] is @scheme[#f] (the
 default). The first string is the Internet address for the local
-machine a viewed by the given TCP port's connection. (For most
+machine a viewed by the given @tech{TCP port}'s connection. (For most
 machines, the answer corresponds to the current machine's only
 Internet address, but when a machine serves multiple addresses, the
 result is connection-specific.) The second string is the Internet
@@ -248,10 +245,10 @@ If the given port has been closed, the @exnraise[exn:fail:network].}
 
 @defproc[(tcp-port? [v any/c]) boolean?]{
 
-Returns @scheme[#t] if @scheme[v] is a port returned by
+Returns @scheme[#t] if @scheme[v] is a @deftech{TCP port}---which is a
-@scheme[tcp-accept], @scheme[tcp-connect],
+port returned by @scheme[tcp-accept], @scheme[tcp-connect],
 @scheme[tcp-accept/enable-break], or
-@scheme[tcp-connect/enable-break], @scheme[#f] otherwise.}
+@scheme[tcp-connect/enable-break]---@scheme[#f] otherwise.}
 
 @;------------------------------------------------------------------------
 @section[#:tag "udp"]{UDP}
@@ -265,7 +262,7 @@ Volume 1} by W. Richard Stevens.
                           [family-port-no (or/c string? #f) #f])
          udp?]{
 
-Creates and returns a UDP socket to send and receive
+Creates and returns a @deftech{UDP socket} to send and receive
 datagrams (broadcasting is allowed). Initially, the socket is not
 bound or connected to any address or port.