Start on a notation section for the Reference

collects/scribblings/reference/intro.scrbl

@@ -0,0 +1,146 @@
+#lang scribble/doc
+@(require scribble/struct scribble/racket "mz.rkt")
+
+@title[#:tag "intro"]{Introduction}
+
+This chapter introduces essential terminology and notation that is
+used throughout the rest of the document and other Racket reference
+manuals.
+
+@section{Notation}
+
+The following sections explain how to read the notation used in Racket
+manuals to describe syntactic forms and values that are provided by
+the base language and by additional libraries.
+
+Syntactic forms, whether provided from the base language or via
+syntactic extensions, are specified using the same format that is
+described in the @guidesecref{syntax-notation} chapter of @|Guide|.
+
+@section{How to Read Module Declarations}
+
+Racket programs are usually organized into @tech{module}s. The Reference
+reflects this organization with a notation for module declarations.
+A module declaration often prefaces the beginning of a Reference section
+or subsection:
+
+@; TODO: change `defmodule` to support this
+@(make-table "defmodule"
+  (list
+   (list
+    (make-flow
+     (list
+      (make-omitable-paragraph
+       (list (hspace 1) (racket (require racket/list)))))))))
+
+The preceding @racket[require] statement indicates that the bindings that would be
+documented below are available in the @racketmodname[racket/list] module. When
+a module name is not explicitly mentioned, it usually indicates that the
+documented bindings are contained in @racketmodname[racket/base].
+
+
+@section{How to Read Contracts for Functions}
+
+Procedures and other values are described using a notation based on
+@tech{contract}s. In essence, these contracts describe the interfaces of
+the documented library using Racket predicates and expressions.
+
+For example, the following is the header of the definition of a
+typical procedure:
+
+@defproc[#:link-target? #f
+         (char->integer [char char?]) exact-integer?]{}
+
+The function being defined, @racket[char->integer], is typeset as if it
+were being applied. The metavariables that come after the function name
+stand in for arguments. The white text in the corner identifies the
+kind of value that is being documented.
+
+Each metavariable is described with a contract. In the preceding
+example, the metavariable @racket[_char] has the contract
+@racket[char?]. This contract specifies that any argument
+@racket[_char] that answers true to the @racket[char?] predicate is
+valid. The documented function may or may not actually check this
+property, but the contract signals the intent of the implementer.
+
+The contract on the right of the arrow, @racket[exact-integer?] in this case,
+specifies the expected result that is produced by the function.
+
+Contract specifications can be more expressive than just names of
+predicates. Consider the following header for @racket[argmax]:
+
+@defproc[#:link-target? #f
+         (argmax [proc (-> any/c real?)]
+                 [lst (and/c pair? list?)])
+         any]{}
+
+The contract @racket[(-> any/c real?)] denotes a function contract specifying
+that @racket[proc]'s argument can be any single value and the result should be
+a real number. The contract @racket[(and/c pair? list?)] for @racket[_lst]
+specifies that @racket[_lst] should pass both @racket[pair?] and @racket[list?]
+(i.e., that it is a non-empty list).
+
+Both @racket[->] and @racket[and/c] are examples of @tech{contract combinator}s.
+Contract combinators such as @racket[or/c], @racket[cons/c], @racket[listof],
+and others are used throughout the documentation. Clicking on the hyperlinked
+combinator name will provide more information on its meaning.
+
+A Racket function may be documented as having one or more optional arguments.
+The @racket[read] function is an example of such a function:
+
+@defproc[#:link-target? #f
+         (read [in input-port? (current-input-port)])
+         any]{}
+
+The brackets surrounding the @racket[_in] argument in the application
+syntax indicates that it is an optional argument.
+
+The header for @racket[read] specifies a contract for the parameter
+@racket[_in] as usual. To the right of the contract, it also specifies
+a default value @racket[(current-input-port)] that is used if
+@racket[read] is called with no arguments.
+
+Functions may also be documented as accepting mandatory or optional
+keyword-based arguments.  For example, the @racket[sort] function has
+two optional, keyword-based arguments:
+
+@defproc[#:link-target? #f
+         (sort [lst list?] [less-than? (any/c any/c . -> . any/c)]
+               [#:key extract-key (any/c . -> . any/c) (lambda (x) x)]
+               [#:cache-keys? cache-keys? boolean? #f]) list?]{}
+
+The brackets around the @racket[_extract-key] and
+@racket[_cache-keys?]  arguments indicate that they are optional as
+before. The contract section of the header shows the default values
+that are provided for these keyword arguments.
+
+@section{How to Read Parameter Contracts}
+
+Parameters are used in Racket for dynamically customizable arguments
+to code. They are documented with a notation similar to function
+contracts:
+
+@defparam[#:link-target? #f
+          current-command-line-arguments
+          argv
+          (vectorof (and/c string? immutable?))]{}
+
+Since parameters can be read or written, there are two entries in the
+header above. Calling @racket[current-command-line-arguments] with no
+arguments is documented to return a vector that contains objects that
+pass both @racket[string?] and @racket[immutable?]. Similarly, the
+single argument case takes a vector with the same specification and
+returns an object satisfying @racket[void?].
+
+@section{How to Read Contracts on Other Values}
+
+Some libraries provide bindings to constant values. These values are
+documented with a separate header:
+
+@defthing[#:link-target? #f object% class?]{}
+
+The @racketmodname[racket/class] library provides the @racket[object%]
+value, which is the root of the class hierarchy in Racket. Its
+documentation header just indicates that it is a value that satisfies
+the predicate @racket[class?].
+

collects/scribblings/reference/reference.scrbl

@@ -57,6 +57,7 @@ The @racketmodname[racket] library combines
 
 @table-of-contents[]
 
+@include-section["intro.scrbl"]
 @include-section["model.scrbl"]
 @include-section["syntax.scrbl"]
 @include-section["data.scrbl"]