From 2d7b97ece9aa6a70a97e4b6dc6ce8fcaea0d5f2b Mon Sep 17 00:00:00 2001
From: Matthew Flatt <mflatt@racket-lang.org>
Date: Sun, 26 Feb 2012 15:39:23 -0500
Subject: [PATCH] doc and terminology fix

---
 collects/scribblings/foreign/types.scrbl        |  4 ++--
 collects/scribblings/reference/file-ports.scrbl |  4 ++--
 collects/scribblings/reference/places.scrbl     | 17 +++++++++++------
 3 files changed, 15 insertions(+), 10 deletions(-)

diff --git a/collects/scribblings/foreign/types.scrbl b/collects/scribblings/foreign/types.scrbl
index 28a354a262..7612febdc8 100644
--- a/collects/scribblings/foreign/types.scrbl
+++ b/collects/scribblings/foreign/types.scrbl
@@ -296,7 +296,7 @@ value of @cpp{NULL} is translated to a Racket @racket[eof] value.}
 
 @defthing[_pointer ctype?]{
 
-Corresponds to Racket ``C pointer'' objects.  These pointers can have
+Corresponds to Racket @deftech{C pointer} values.  These pointers can have
 an arbitrary Racket object attached as a type tag.  The tag is ignored
 by built-in functionality; it is intended to be used by interfaces.
 See @secref["foreign:tagged-pointers"] for creating pointer types that
@@ -316,7 +316,7 @@ refer to the same address.}
 
 @defthing[_gcpointer ctype?]{
 
-Like @racket[_pointer], but for a value that can refer to memory
+Like @racket[_pointer], but for a C pointer value that can refer to memory
 managed by the garbage collector.
 
 Although a @racket[_gcpointer] can reference to memory that is not
diff --git a/collects/scribblings/reference/file-ports.scrbl b/collects/scribblings/reference/file-ports.scrbl
index be489219d9..809137db2d 100644
--- a/collects/scribblings/reference/file-ports.scrbl
+++ b/collects/scribblings/reference/file-ports.scrbl
@@ -197,9 +197,9 @@ A @tech{path} value that is the @tech{cleanse}d version of
 
 Like @racket[open-output-file], but producing two values: an input
 port and an output port. The two ports are connected in that they
-share the underlying file device. This procedure is intended for use
+share the underlying file descriptor. This procedure is intended for use
 with special devices that can be opened by only one process, such as
-@filepath{COM1} in Windows. For regular files, sharing the device can be
+@filepath{COM1} in Windows. For regular files, sharing the file descriptor can be
 confusing. For example, using one port does not automatically flush
 the other port's buffer, and reading or writing in one port moves the
 file position (if any) for the other port. For regular files, use
diff --git a/collects/scribblings/reference/places.scrbl b/collects/scribblings/reference/places.scrbl
index 7095204d2b..65c5b75035 100644
--- a/collects/scribblings/reference/places.scrbl
+++ b/collects/scribblings/reference/places.scrbl
@@ -303,12 +303,16 @@ messages:
  @item{@tech{numbers}, @tech{characters}, @tech{booleans}, and
        @|void-const|;}
 
- @item{@tech{symbols};}
+ @item{@tech{symbols}, where the @racket[eq?]ness of @tech{uninterned}
+       symbols is preserved within a single message, but not across
+       messages;}
  
  @item{@tech{strings} and @tech{byte strings}, where mutable strings
        and byte strings are automatically replaced by immutable
        variants;}
 
+ @item{@tech{paths} (for any platform);}
+
  @item{@tech{pairs}, @tech{lists}, @tech{vectors}, and immutable
        @tech{prefab} structures containing message-allowed values,
        where a mutable vector is automatically replaced by an
@@ -317,12 +321,13 @@ messages:
  @item{@tech{place channels}, where a @tech{place descriptor} is
        automatically replaced by a plain place channel;}
 
- @item{foreign pointers such as @racket[_cpointers] and 
-       cstructs;}
+ @item{@tech{file-stream ports} and @tech{TCP ports}, where the
+       underlying representation (such as a file descriptor, socket,
+       or handle) is duplicated and attached to a fresh port in the
+       receiving place;}
 
- @item{file ports and tcp ports, the underlying 
-       file descriptor is dupped and a new port is created with the 
-       dupped file descriptor in the destination place; and}
+ @item{@tech[#:doc '(lib "scribblings/foreign/foreign.scrbl")]{C
+       pointers} as created or accessed via @racketmodname[ffi/unsafe]; and}
 
  @item{values produced by @racket[shared-flvector],
        @racket[make-shared-flvector], @racket[shared-fxvector],