From 7ace3962faecd73c593a04fbc59f6d619d39a8d6 Mon Sep 17 00:00:00 2001
From: Robby Findler <robby@racket-lang.org>
Date: Mon, 13 Oct 2008 22:31:43 +0000
Subject: [PATCH] improved overview a little

svn: r12027
---
 .../scribblings/reference/contracts.scrbl     | 61 ++++++++++++-------
 1 file changed, 38 insertions(+), 23 deletions(-)

diff --git a/collects/scribblings/reference/contracts.scrbl b/collects/scribblings/reference/contracts.scrbl
index efcb6d0214..3df14cd5cb 100644
--- a/collects/scribblings/reference/contracts.scrbl
+++ b/collects/scribblings/reference/contracts.scrbl
@@ -9,15 +9,33 @@ and pragmatics of using contracts. See
 @guidesecref["contracts"] in the Guide for more of the
 latter and less of the former.
 
-A @defterm{contract} controls the flow of values to ensure that the
-expectations of one party are met by another party.  The
-@scheme[provide/contract] form is the primary mechanism for
-associating a contract with a binding.
+The contract system guards one part of a program from
+another. Programmers specify the behavior of a module exports via
+@scheme[provide/contract] and the contract system enforces those
+constraints.
 
-Note that all of the combinators that accept contracts as arguments
-use @scheme[coerce-contract], meaning that symbols, booleans, strings,
-bytess, characters, numbers, regular expressions, and predicates
-are all implicitly converted into contracts.
+@deftech{Contracts} come in two forms: those constructed by the
+various operations listed in this section of the manual, and various
+ordinary Scheme values double as contracts, including 
+@itemize{
+@item{@tech{symbols}, @tech{booleans}, @tech{characters}, and
+@scheme[null], which are treated as contracts that recognize
+themselves, using @scheme[eq?], }
+
+@item{@tech{strings} and @tech{bytes strings}, which are treated as contracts
+that recognize themselves using @scheme[equal?], }
+
+@item{@tech{numbers}, which are treated as contracts
+that recognize themselves using @scheme[=],}
+
+@item{@tech{regular expressions}, which are treated as contracts that recognize @tech{byte strings} and @tech{strings} that match the regular expression, and }
+
+@item{predicates: any procedure whose arity is 1 is treated as a
+predicate. During contract checking, it is applied to the values that
+appear and should return @scheme[#f] to indicate that the contract
+failed, and anything else to indicate it passed.}
+
+}
 
 @note-lib[scheme/contract #:use-sources (scheme/private/contract-ds
                                          scheme/private/contract
@@ -905,19 +923,12 @@ extracts the names from any contracts it is supplied with.}
 
 @defproc[(coerce-contract [id symbol?] [x any/c]) contract?]{
 
-If @scheme[x] is a contract, it returns it. If it is a procedure of
-arity one, it converts that into a contract by treating the result as
-a predicate. If it is a symbol, boolean, or character, it makes a
-contract that accepts values that are @scheme[eq?] to @scheme[x]. If
-@scheme[x] is a string or a bytes, it makes a contract that
-accespts values that are @scheme[equal?] to @scheme[x]. If @scheme[x]
-is a regular expression or a byte regular expression, it makes a
-contract that accepts strings and bytes, as long as they match the
-regular expression.
+Converts a regular scheme value into an instance of a contract struct,
+converting it according to the description of @tech{contracts}.
 
-If @scheme[x] is none of the above, @scheme[coerce-contract]
-signals an error, using the first argument in the error
-message.}
+If @scheme[x] is not one of the coercable values,
+@scheme[coerce-contract] signals an error, using the first argument in
+the error message.}
 
 @defproc[(coerce-contracts [id symbol?] [xs (listof any/c)]) (listof contract?)]{
 
@@ -986,9 +997,13 @@ otherwise.}
 
 @defproc[(flat-contract? [v any/c]) boolean?]{
 
-Returns @scheme[#t] when its argument is a contract that has been
-constructed with @scheme[flat-contract] (and thus is essentially just
-a predicate), @scheme[#f] otherwise.}
+Returns @scheme[#t] when its argument is a contract that can be
+checked immediately (unlike, say, a function contract). 
+
+For example,
+@scheme[flat-contract] constructs flat contracts from predicates, and
+symbols, booleans, numbers, and other ordinary Scheme values are also
+flat contracts.}
 
 @defproc[(flat-contract-predicate [v flat-contract?])
          (any/c . -> . any/c)]{