From 0b496d5275e1bfacb9c087f2548a80fbb3878d26 Mon Sep 17 00:00:00 2001 From: Matthew Flatt Date: Thu, 10 Mar 2011 06:34:33 -0600 Subject: [PATCH] a round of doc corrections from Gwyth --- .../reference/async-channels.scrbl | 2 +- collects/scribblings/reference/booleans.scrbl | 6 +- collects/scribblings/reference/bytes.scrbl | 6 +- collects/scribblings/reference/channels.scrbl | 11 ++-- collects/scribblings/reference/class.scrbl | 2 +- collects/scribblings/reference/cont.scrbl | 2 +- .../scribblings/reference/contracts.scrbl | 44 ++++++------- .../scribblings/reference/control-lib.scrbl | 6 +- .../scribblings/reference/custom-ports.scrbl | 25 ++++--- .../scribblings/reference/custom-write.scrbl | 8 +-- .../scribblings/reference/define-struct.scrbl | 2 +- .../scribblings/reference/encodings.scrbl | 8 +-- .../scribblings/reference/eval-model.scrbl | 4 +- .../scribblings/reference/file-ports.scrbl | 14 ++-- collects/scribblings/reference/match.scrbl | 10 +-- collects/scribblings/reference/numbers.scrbl | 2 +- collects/scribblings/reference/pairs.scrbl | 2 +- collects/scribblings/reference/pipes.scrbl | 2 +- collects/scribblings/reference/places.scrbl | 10 +-- .../scribblings/reference/port-buffers.scrbl | 12 ++-- collects/scribblings/reference/port-lib.scrbl | 40 +++++------ .../reference/port-line-counting.scrbl | 4 +- .../scribblings/reference/port-procs.scrbl | 2 +- collects/scribblings/reference/ports.scrbl | 2 +- .../scribblings/reference/pretty-print.scrbl | 22 +++---- collects/scribblings/reference/printer.scrbl | 66 +++++++++---------- .../scribblings/reference/prop-port.scrbl | 8 +-- collects/scribblings/reference/read.scrbl | 8 +-- collects/scribblings/reference/reader.scrbl | 58 ++++++++-------- .../scribblings/reference/readtables.scrbl | 16 ++--- collects/scribblings/reference/regexps.scrbl | 4 +- collects/scribblings/reference/sandbox.scrbl | 2 +- .../scribblings/reference/semaphores.scrbl | 12 ++-- .../scribblings/reference/sequences.scrbl | 2 +- .../scribblings/reference/serialization.scrbl | 18 ++--- collects/scribblings/reference/startup.scrbl | 2 +- .../scribblings/reference/string-input.scrbl | 20 +++--- .../scribblings/reference/string-output.scrbl | 6 +- .../scribblings/reference/string-ports.scrbl | 4 +- collects/scribblings/reference/strings.scrbl | 4 +- .../scribblings/reference/stx-trans.scrbl | 4 +- .../scribblings/reference/syntax-model.scrbl | 6 +- collects/scribblings/reference/syntax.scrbl | 47 +++++++------ .../scribblings/reference/thread-cells.scrbl | 11 ++-- collects/scribblings/reference/time.scrbl | 2 +- collects/scribblings/reference/units.scrbl | 2 +- collects/scribblings/reference/write.scrbl | 12 ++-- collects/scribblings/scribble/style.scrbl | 8 ++- 48 files changed, 291 insertions(+), 279 deletions(-) diff --git a/collects/scribblings/reference/async-channels.scrbl b/collects/scribblings/reference/async-channels.scrbl index d2c78136a2..55df5fa04c 100644 --- a/collects/scribblings/reference/async-channels.scrbl +++ b/collects/scribblings/reference/async-channels.scrbl @@ -54,7 +54,7 @@ Puts @scheme[v] into @scheme[ach], blocking if @scheme[ach]'s buffer is full until space is available.} -@defproc[(async-channel-put-evt [ach channel?] [v any/c]) +@defproc[(async-channel-put-evt [ach async-channel?] [v any/c]) evt?]{ Returns a @tech{synchronizable event} that is blocked while diff --git a/collects/scribblings/reference/booleans.scrbl b/collects/scribblings/reference/booleans.scrbl index 8e00d102bb..216ba189eb 100644 --- a/collects/scribblings/reference/booleans.scrbl +++ b/collects/scribblings/reference/booleans.scrbl @@ -219,13 +219,13 @@ non-@racket[#f] value when applied to the structure. (equal? west south) ]} -@section{Boolean Synonyms} +@section{Boolean Aliases} @note-lib[racket/bool] -@defthing[true boolean?]{A synonym for @scheme[#t].} +@defthing[true boolean?]{An alias for @scheme[#t].} -@defthing[false boolean?]{A synonym for @scheme[#f].} +@defthing[false boolean?]{An alias for @scheme[#f].} @defproc[(symbol=? [a symbol?] [b symbol?]) boolean?]{ diff --git a/collects/scribblings/reference/bytes.scrbl b/collects/scribblings/reference/bytes.scrbl index 0320184f0c..66795c730a 100644 --- a/collects/scribblings/reference/bytes.scrbl +++ b/collects/scribblings/reference/bytes.scrbl @@ -157,7 +157,7 @@ string. @defproc[(bytes->list [bstr bytes?]) (listof byte?)]{ Returns a new list of bytes corresponding to the content of @scheme[bstr]. That is, the length of the list is @scheme[(bytes-length bstr)], and the - sequence of bytes of @scheme[bstr] is the same sequence in the + sequence of bytes in @scheme[bstr] is the same sequence in the result list. @mz-examples[(bytes->list #"Apple")]} @@ -166,7 +166,7 @@ string. @defproc[(list->bytes [lst (listof byte?)]) bytes?]{ Returns a new mutable byte string whose content is the list of bytes in @scheme[lst]. That is, the length of the byte string is @scheme[(length lst)], and - the sequence of bytes in @scheme[lst] is in the same sequence in + the sequence of bytes in @scheme[lst] is the same sequence in the result byte string. @mz-examples[(list->bytes (list 65 112 112 108 101))]} @@ -229,7 +229,7 @@ When @secref["places"] are enabled, the new byte string is allocated in the substring of @scheme[bstr] as a UTF-8 encoding of Unicode code points. If @scheme[err-char] is not @scheme[#f], then it is used for bytes that fall in the range @scheme[#o200] to @scheme[#o377] but are - not part of a valid encoding sequence. (This is consistent with + not part of a valid encoding sequence. (This rule is consistent with reading characters from a port; see @secref["encodings"] for more details.) If @scheme[err-char] is @scheme[#f], and if the @scheme[start] to @scheme[end] substring of @scheme[bstr] is not a diff --git a/collects/scribblings/reference/channels.scrbl b/collects/scribblings/reference/channels.scrbl index 5406fba87d..7a1cf66ce1 100644 --- a/collects/scribblings/reference/channels.scrbl +++ b/collects/scribblings/reference/channels.scrbl @@ -16,6 +16,11 @@ often, then the thread eventually participates in a transaction. For buffered asynchronous channels, see @secref["async-channel"]. +@defproc[(channel? [v any/c]) boolean?]{ + +Returns @scheme[#t] if @scheme[v] is a @tech{channel}, +@scheme[#f] otherwise.} + @defproc[(make-channel) channel?]{ Creates and returns a new channel. The channel can be used with @@ -25,12 +30,6 @@ through the channel. The channel can be used with @scheme[channel-put] or through the result of @scheme[channel-put-evt] to send a value through the channel.} -@defproc[(channel? [v any/c]) boolean?]{ - -Returns @scheme[#t] if @scheme[v] is a channel created by -@scheme[make-channel], @scheme[#f] otherwise.} - - @defproc[(channel-get [ch channel?]) any]{ Blocks until a sender is ready to provide a value through diff --git a/collects/scribblings/reference/class.scrbl b/collects/scribblings/reference/class.scrbl index 2e0ab466dd..5053484249 100644 --- a/collects/scribblings/reference/class.scrbl +++ b/collects/scribblings/reference/class.scrbl @@ -640,7 +640,7 @@ Each @scheme[public], @scheme[override], @scheme[augment], @scheme[augment-final], and @scheme[private] clause in a class declares one or more method names. Each method name must have a corresponding @scheme[method-definition]. The order of -@scheme[public], @|etc| clauses and their corresponding definitions +@scheme[public], @|etc|, clauses and their corresponding definitions (among themselves, and with respect to other clauses in the class) does not matter. diff --git a/collects/scribblings/reference/cont.scrbl b/collects/scribblings/reference/cont.scrbl index 731c088826..cdbcddc0ed 100644 --- a/collects/scribblings/reference/cont.scrbl +++ b/collects/scribblings/reference/cont.scrbl @@ -181,7 +181,7 @@ than @racket[call-with-current-continuation]. A continuation obtained from @racket[call-with-escape-continuation] is actually a kind of prompt. Escape continuations are provided mainly -for backward compatibility, since they pre-date general prompts in +for backwards compatibility, since they pre-date general prompts in Racket, and because @racket[call/ec] is often an easy replacement for @racket[call/cc] to improve performance.} diff --git a/collects/scribblings/reference/contracts.scrbl b/collects/scribblings/reference/contracts.scrbl index 459b6882bd..12e967d465 100644 --- a/collects/scribblings/reference/contracts.scrbl +++ b/collects/scribblings/reference/contracts.scrbl @@ -182,7 +182,7 @@ input to be a real number between @racket[n] and @racket[m] or equal to one of them.} @defproc[(real-in [n real?] [m real?]) flat-contract?]{ -This is an alias for @racket[between/c].} +An alias for @racket[between/c].} @defproc[(integer-in [j exact-integer?] [k exact-integer?]) flat-contract?]{ @@ -203,7 +203,7 @@ Returns a flat contract that recognizes strings that have fewer than @defthing[false/c flat-contract?]{ -This is just @racket[#f]. It is here for backwards compatibility.} +An alias @racket[#f] for backwards compatibility.} @defthing[printable/c flat-contract?]{ @@ -217,8 +217,8 @@ read back in with @racket[write] and @racket[read].} Accepts any number of atomic values and returns a flat contract that recognizes those values, using @racket[eqv?] as the comparison predicate. For the purposes of @racket[one-of/c], atomic values are -defined to be: characters, symbols, booleans, null keywords, numbers, -void, and undefined.} +defined to be: @tech{characters}, @tech{symbols}, @tech{booleans}, @racket[null], @tech{keywords}, @tech{numbers}, +@|void-const|, and @|undefined-const|.} @defproc[(symbols [sym symbol?] ...+) flat-contract?]{ @@ -249,8 +249,8 @@ and a @tech{chaperone} or @tech{impersonator} of the input for mutable vectors.} @defproc[(vector-immutableof [c contract?]) contract?]{ -Returns the same contract as @racket[(vectorof c #:immutable #t)]. This exists for -reasons of backwards compatibility, and may be removed in the future.} +Returns the same contract as @racket[(vectorof c #:immutable #t)]. This form exists for +backwards compatibility.} @defproc[(vector/c [c contract?] ... [#:immutable immutable (or/c #t #f 'dont-care) 'dont-care] @@ -275,8 +275,8 @@ and a @tech{chaperone} or @tech{impersonator} of the input for mutable vectors.} @defproc[(vector-immutable/c [c contract?] ...) contract?]{ -Returns the same contract as @racket[(vector/c c ... #:immutable #t)]. This exists for -reasons of backwards compatibility, and may be removed in the future.} +Returns the same contract as @racket[(vector/c c ... #:immutable #t)]. This form exists for +reasons of backwards compatibility.} @defproc[(box/c [c contract?] @@ -301,8 +301,8 @@ and either a @tech{chaperone} or @tech{impersonator} of the input for mutable bo @defproc[(box-immutable/c [c contract?]) contract?]{ -Returns the same contract as @racket[(box/c c #:immutable #t)]. This exists for -reasons of backwards compatibility, and may be removed in the future.} +Returns the same contract as @racket[(box/c c #:immutable #t)]. This form exists for +reasons of backwards compatibility.} @defproc[(listof [c (or/c contract? (any/c . -> . any/c))]) contract?]{ @@ -320,7 +320,7 @@ a value, the result is not necessarily @racket[eq?] to the input.} @defproc[(cons/c [car-c contract?] [cdr-c contract?]) contract?]{ -Produces a contract the recognizes pairs whose first and second elements +Produces a contract that recognizes pairs whose first and second elements match @racket[car-c] and @racket[cdr-c], respectively. Beware that when this contract is applied to a value, the result is not necessarily @racket[eq?] to the input.} @@ -402,7 +402,7 @@ For example, the contract is a flat contract that checks for (a limited form of) S-expressions. It says that a @racket[sexp] is either two -@racket[sexp] combined with @racket[cons], or a number, or a symbol. +@racket[sexp]s combined with @racket[cons], or a number, or a symbol. Note that if the contract is applied to a circular value, contract checking will not terminate.} @@ -449,7 +449,7 @@ result value meets the contract produced by @racket[expr].} Then, when the function returns, it is checked to determine whether the result is wrapped, since the second @racket[a] appears in a positive position. - This is a dual to @racket[new-∃/c]. + The @racket[new-∀/c] construct constructor is dual to @racket[new-∃/c]. } @@ -474,7 +474,7 @@ result value meets the contract produced by @racket[expr].} Then, when the function returns, it is checked to see if the result is wrapped, since the second @racket[a] appears in a negative position. - This is a dual to @racket[new-∀/c]. + The @racket[new-∃/c] construct constructor is dual to @racket[new-∀/c]. } @@ -519,7 +519,7 @@ result of the function. @margin-note{Using a @racket[->] between two whitespace-delimited @racketparenfont{.}s is the same as putting the @racket[->] right -after the enclosing open parenthesis. See +after the enclosing opening parenthesis. See @guidesecref["lists-and-syntax"] or @secref["parse-pair"] for more information.} @@ -661,7 +661,7 @@ expression is evaluated rather than the time when the function is called or returns. These dependency-free contract expressions are evaluated in the order in which they are listed. @; -Second, the dependent contract subexpressions are evaluated when the +Second, the dependent contract sub-expressions are evaluated when the contracted function is called or returns in some order that satisfies the dependencies. That is, if a contract for an argument depends on the value of some other contract, the former is evaluated first (so that the @@ -720,7 +720,7 @@ will allow @racket[f] to be called with @racket[#f], trigger whatever bad behavior the author of @scheme[f] was trying to prohibit by insisting that @racket[f]'s contract accept only integers. -The @racket[#:pre-cond] and @racket[#:post-cond] keywords are synonyms for +The @racket[#:pre-cond] and @racket[#:post-cond] keywords are aliases for @racket[#:pre] and @racket[#:post] and are provided for backwards compatibility. } @@ -1062,7 +1062,7 @@ accepted by the third argument to @racket[datum->syntax]. Contracts are represented internally as functions that accept information about the contract (who is to blame, -source locations, etc) and produce projections (in the +source locations, @|etc|) and produce projections (in the spirit of Dana Scott) that enforce the contract. A projection is a function that accepts an arbitrary value, and returns a value that satisfies the corresponding @@ -1165,7 +1165,7 @@ blames what it sees as positive, we can swap the blame parties by calling @racket[blame-swap] on the given @tech{blame object}, replacing the positive party with the negative party and vice versa. -This is not just a cheap trick to get this example to work, +This technique is not merely a cheap trick to get the example to work, however. The reversal of the positive and the negative is a natural consequence of the way functions behave. That is, imagine the flow of values in a program between two @@ -1624,7 +1624,7 @@ combinators, use the following properties: list and @racket[#:pre] in the second list.} @item{@racketblock0['racket/contract:negative-position : symbol?] - This property should be attached to subexpressions of + This property should be attached to sub-expressions of a contract combinator that are expected to be other contracts. The value of the property should be the key (the first element from the vector for the @racket['racket/contract:contract] property) @@ -1634,7 +1634,7 @@ combinators, use the following properties: that clients are responsible for. } @item{@racketblock0['racket/contract:positive-position : symbol?] - This is just like @racket['racket/contract:negative-position], + This form is just like @racket['racket/contract:negative-position], except that it should be used when the expression's value is a contract that the original party should be responsible for. } @@ -1758,7 +1758,7 @@ name @racket[sexp-name] when signaling a contract violation.} proc (-> blame? any/c string? string?)]{ -This is a parameter that is used when constructing a +A parameter that is used when constructing a contract violation error. Its value is procedure that accepts three arguments: @itemize[ diff --git a/collects/scribblings/reference/control-lib.scrbl b/collects/scribblings/reference/control-lib.scrbl index db1279297d..b46fa49368 100644 --- a/collects/scribblings/reference/control-lib.scrbl +++ b/collects/scribblings/reference/control-lib.scrbl @@ -15,7 +15,7 @@ The @scheme[racket/control] library provides various control operators from the research literature on higher-order control operators, plus a few extra convenience forms. These control operators are implemented in terms of @scheme[call-with-continuation-prompt], -@scheme[call-with-composable-continuations], etc., and they generally +@scheme[call-with-composable-continuations], @|etc|, and they generally work sensibly together. Many are redundant; for example, @scheme[reset] and @scheme[prompt] are aliases. @@ -160,7 +160,7 @@ tags.} @defform[(shift0 id expr ...+)] )]{ -Generalizations of @scheme[prompt], etc. @cite["Shan04"]. +Generalizations of @scheme[prompt], @|etc| @cite["Shan04"]. The essential reduction rules are: @@ -200,7 +200,7 @@ behavior, otherwise the non-@scheme[0] behavior applies.} @defform[(shift0-at prompt-tag-expr id expr ...+)] )]{ -Variants of @scheme[prompt0], @|etc| that accept a prompt tag.} +Variants of @scheme[prompt0], @|etc|, that accept a prompt tag.} @; ---------------------------------------------------------------------- diff --git a/collects/scribblings/reference/custom-ports.scrbl b/collects/scribblings/reference/custom-ports.scrbl index 866e1ef36a..6ee9dfc8c0 100644 --- a/collects/scribblings/reference/custom-ports.scrbl +++ b/collects/scribblings/reference/custom-ports.scrbl @@ -74,7 +74,7 @@ The arguments implement the port as follows: @item{a @tech{synchronizable event} (see @secref["sync"]) other than a pipe input port or procedure of arity four; the event becomes ready when the read is complete (roughly): the event's - value can one of the above three results or another event like + value can be one of the above three results or another event like itself; in the last case, a reading process loops with @scheme[sync] until it gets a non-event result.} @@ -116,8 +116,8 @@ The arguments implement the port as follows: @scheme[peek-in] procedure is called again (instead of using the pipe, for whatever reason). If @scheme[read-in] or @scheme[peek-in] is called, any previously associated pipe (as - returned by a previous call) will have been disassociated from the - port, and is not in use by any other thread as a result of the + returned by a previous call) is disassociated from the + port and is not in use by any other thread as a result of the previous association. If @scheme[peek], @scheme[get-progress-evt], and @@ -278,12 +278,12 @@ The arguments implement the port as follows: given progress event is ready, whichever is first.} @item{It can report an error by raising an exception, but only if - no data is committed. In other words, no data should be lost due to + no data has been committed. In other words, no data should be lost due to an exception, including a break exception.} - @item{It must return a true value if data is committed, + @item{It must return a true value if data has been committed, @scheme[#f] otherwise. When it returns a value, the given - progress event must be ready (perhaps because data was just + progress event must be ready (perhaps because data has just been committed).} @item{It must raise an exception if no data (including @@ -336,7 +336,7 @@ The arguments implement the port as follows: @elemtag["special"]{@bold{``Special'' results:}} When @scheme[read-in] or @scheme[peek] (or an event produced by one of - these) returns a procedure, and the procedure is used to obtain a + these) returns a procedure, the procedure is used to obtain a non-byte result. (This non-byte result is @italic{not} intended to return a character or @scheme[eof]; in particular, @scheme[read-char] raises an exception if it encounters a special-result procedure, even @@ -813,7 +813,7 @@ procedures. will be @scheme[#t], which indicates that @scheme[write-out] should re-enable breaks while blocking. - If the writing procedure raises an exception, due either to write + If the writing procedure raises an exception, due to write or commit operations, it must not have committed any bytes (though it may have committed previously buffered bytes). @@ -861,7 +861,7 @@ procedures. Since @scheme[write-out-special] can return an event, passing the first argument to an implementation of - @scheme[get-write-special-evt] is acceptable as an + @scheme[get-write-special-evt] is acceptable as a @scheme[write-out-special]. As for @scheme[write-out], the @scheme[#f] result is discouraged, @@ -880,7 +880,7 @@ procedures. @item{an immutable byte string containing bytes to write;} @item{a non-negative exact integer for a starting offset - (inclusive) into the byte string, and} + (inclusive) into the byte string; and} @item{a non-negative exact integer for an ending offset (exclusive) into the byte string.} @@ -897,7 +897,6 @@ procedures. @scheme[port-writes-atomic?] will produce @scheme[#f] when applied to the port, and the port will not be a valid argument to procedures such as @scheme[write-bytes-avail-evt]. - Otherwise, an event returned by @scheme[get-write-evt] must not cause data to be written to the port unless the event is chosen in a synchronization, and it must write to the port if the @@ -911,7 +910,7 @@ procedures. when the buffer is completely flushed. (If the port has no buffer, then it is effectively always flushed.) - If the event raises an exception, due either to write or commit + If the event raises an exception, due to write or commit operations, it must not have committed any new bytes (though it may have committed previously buffered bytes). @@ -931,7 +930,7 @@ procedures. write. The resulting event (with its constraints) is analogous to the result of @scheme[get-write-evt]. - If the event raises an exception, due either to write or commit + If the event raises an exception, due to write or commit operations, it must not have committed the special value (though it may have committed previously buffered bytes and values).} diff --git a/collects/scribblings/reference/custom-write.scrbl b/collects/scribblings/reference/custom-write.scrbl index 4bbe6a3e06..cc3cb790e9 100644 --- a/collects/scribblings/reference/custom-write.scrbl +++ b/collects/scribblings/reference/custom-write.scrbl @@ -5,7 +5,7 @@ @defthing[prop:custom-write struct-type-property?]{ -Associates a procedure to a structure type to used by the default +Associates a procedure to a structure type used by the default printer to @scheme[display], @scheme[write], or @scheme[print] instances of the structure type. @@ -27,8 +27,8 @@ the port through @scheme[display], @scheme[write], or @scheme[print] prints a value recursively with sharing annotations. To avoid a recursive print (i.e., to print without regard to sharing with a value currently being printed), print instead to a string or pipe and -transfer the result to the target port using @scheme[write-string] and -@scheme[write-special]. To recursively print but to a port other than +transfer the result to the target port using @scheme[write-string] or +@scheme[write-special]. To print recursively to a port other than the one given to the custom-write procedure, copy the given port's write handler, display handler, and print handler to the other port. @@ -85,7 +85,7 @@ property, @scheme[#f] otherwise.} @defproc[(custom-write-accessor [v custom-write?]) - (custom-write? output-port? boolean?. -> . any)]{ + (custom-write? output-port? boolean? . -> . any)]{ Returns the custom-write procedure associated with @scheme[v].} diff --git a/collects/scribblings/reference/define-struct.scrbl b/collects/scribblings/reference/define-struct.scrbl index 6ddd59ef6c..234355b4ff 100644 --- a/collects/scribblings/reference/define-struct.scrbl +++ b/collects/scribblings/reference/define-struct.scrbl @@ -221,7 +221,7 @@ Like @racket[struct], except that the syntax for supplying a a @racketidfont{make-} prefix on @racket[id] is implicitly supplied via @racket[#:extra-constructor-name]. -This form is provided for backward compatibility; @racket[struct] is +This form is provided for backwards compatibility; @racket[struct] is preferred. @defexamples[ diff --git a/collects/scribblings/reference/encodings.scrbl b/collects/scribblings/reference/encodings.scrbl index a5bbe48382..0da663012f 100644 --- a/collects/scribblings/reference/encodings.scrbl +++ b/collects/scribblings/reference/encodings.scrbl @@ -35,7 +35,7 @@ of characters. A @deftech{locale} captures information about a user's -culture-specific interpretation of character sequences. In particular, +language-specific interpretation of character sequences. In particular, a locale determines how strings are ``alphabetized,'' how a lowercase character is converted to an uppercase character, and how strings are compared without regard to case. String operations such as @@ -67,7 +67,7 @@ but the @racket[""] locale means the current user's default locale; under Windows and Mac OS X, the encoding for @racket[""] is always UTF-8, and locale-sensitive operations use the operating system's native interface. (In particular, setting the @envvar{LC_ALL} and -@envvar{LC_CTYPE} environment variables do not affect the locale +@envvar{LC_CTYPE} environment variables does not affect the locale @racket[""] under Mac OS X. Use @racket[getenv] and @racket[current-locale] to explicitly install the environment-specified locale, if desired.) Setting the current locale @@ -81,10 +81,10 @@ A parameter that determines the current @tech{locale} for procedures such as @racket[string-locale-ci=?]. When locale sensitivity is disabled by setting the parameter to -@racket[#f], strings are compared (etc.) in a fully portable manner, +@racket[#f], strings are compared, etc., in a fully portable manner, which is the same as the standard procedures. Otherwise, strings are interpreted according to a locale setting (in the sense of the C -library's @tt{setlocale}). The @racket[""] locale is always a synonym +library's @tt{setlocale}). The @racket[""] locale is always an alias for the current machine's default locale, and it is the default. The @racket["C"] locale is also always available; setting the locale to @racket["C"] is the same as disabling locale sensitivity with diff --git a/collects/scribblings/reference/eval-model.scrbl b/collects/scribblings/reference/eval-model.scrbl index 4804637f11..5372525253 100644 --- a/collects/scribblings/reference/eval-model.scrbl +++ b/collects/scribblings/reference/eval-model.scrbl @@ -761,7 +761,7 @@ outermost frame of the continuation for any new thread. A @deftech{custodian} manages a collection of threads, @tech{file-stream ports}, TCP ports, @tech{TCP listeners}, @tech{UDP -sockets}, and @tech{byte converters}. Whenever a thread, etc. is +sockets}, and @tech{byte converters}. Whenever a thread, @|etc|, is created, it is placed under the management of the @deftech{current custodian} as determined by the @racket[current-custodian] @tech{parameter}. @@ -775,7 +775,7 @@ custodian's owner. When a @tech{custodian} is shut down via @racket[custodian-shutdown-all], it forcibly and immediately closes -the ports, TCP connections, etc. that it manages, as well as +the ports, TCP connections, @|etc|, that it manages, as well as terminating (or suspending) its threads. A custodian that has been shut down cannot manage new objects. If the current custodian is shut down before a procedure is called to create a managed resource (e.g., diff --git a/collects/scribblings/reference/file-ports.scrbl b/collects/scribblings/reference/file-ports.scrbl index 94a6ec95ad..1fd182d085 100644 --- a/collects/scribblings/reference/file-ports.scrbl +++ b/collects/scribblings/reference/file-ports.scrbl @@ -79,7 +79,7 @@ attempting to use @racket['text] with other kinds of files triggers an @racket[exn:fail:filesystem] exception. Otherwise, the file specified by @racket[path] need not be a regular -file. It might a device that is connected through the filesystem, such +file. It might be a device that is connected through the filesystem, such as @filepath{aux} under Windows or @filepath{/dev/null} under Unix. In all cases, the port is buffered by default. @@ -88,7 +88,7 @@ closed, either though @racket[close-input-port] or indirectly via @racket[custodian-shutdown-all], to release the OS-level file handle. The input port will not be closed automatically if it is otherwise available for garbage collection (see -@secref["gc-model"]); a @tech{will} could be associated input port +@secref["gc-model"]); a @tech{will} could be associated with an input port to close it more automatically (see @secref["willexecutor"]). A @tech{path} value that is the @tech{cleanse}d version of @@ -168,17 +168,17 @@ files that already exist: ] The file specified by @racket[path] need not be a regular file. It -might a device that is connected through the filesystem, such as +might be a device that is connected through the filesystem, such as @filepath{aux} under Windows or @filepath{/dev/null} under Unix. The output port is block-buffered by default, unless the file corresponds to a -terminal, in which case is it line buffered bu default. +terminal, in which case it is line-buffered by default. The port produced by @racket[open-output-port] should be explicitly closed, either though @racket[close-output-port] or indirectly via @racket[custodian-shutdown-all], to release the OS-level file handle. The output port will not be closed automatically if it is otherwise available for garbage collection (see -@secref["gc-model"]); a @tech{will} could be associated input port +@secref["gc-model"]); a @tech{will} could be associated with an output port to close it more automatically (see @secref["willexecutor"]). A @tech{path} value that is the @tech{cleanse}d version of @@ -215,13 +215,13 @@ Calls @racket[open-input-file] with the @racket[path] and @racket[mode-flag] arguments, and passes the resulting port to @racket[proc]. The result of @racket[proc] is the result of the @racket[call-with-input-file] call, but the newly opened port is closed -when @racket[thunk] return. +when @racket[proc] returns. @file-examples[ (with-output-to-file some-file (lambda () (printf "text in a file"))) (call-with-input-file some-file - (lambda (in) (read-string 15 in))) + (lambda (in) (read-string 14 in))) ]} @defproc[(call-with-output-file [path path-string?] diff --git a/collects/scribblings/reference/match.scrbl b/collects/scribblings/reference/match.scrbl index a89d8f7bec..3e99d3d9db 100644 --- a/collects/scribblings/reference/match.scrbl +++ b/collects/scribblings/reference/match.scrbl @@ -26,7 +26,7 @@ bindings introduced by @racket[pat] (if any). The last @racket[body] in the matching clause is evaluated in tail position with respect to the @racket[match] expression. -The @racket[clause]s are tried in order to find a match. If no +To find a match, the @racket[clause]s are tried in order. If no @racket[clause] matches, then the @exnraise[exn:misc:match?]. An optional @racket[(=> id)] between a @racket[pat] and the @@ -95,9 +95,9 @@ In more detail, patterns match as follows: corresponds to a ``spliced'' list of greedy matches. For spliced lists, @racketidfont{...} and @racketidfont{___} - are synonyms for zero or more matches. The + are aliases for zero or more matches. The @racketidfont{..}@racket[_k] and @racketidfont{__}@racket[_k] - forms are also synonyms, specifying @racket[_k] or more + forms are also aliases, specifying @racket[_k] or more matches. Pattern variables that precede these splicing operators are bound to lists of matching forms. @@ -439,14 +439,14 @@ A predicate for the exception raised in the case of a match failure. Binds @racket[id] to a @deftech{match expander}. -The first @racket[proc-expr] subexpression must evaluate to a +The first @racket[proc-expr] sub-expression must evaluate to a transformer that produces a @racket[_pat] for @racket[match]. Whenever @racket[id] appears as the beginning of a pattern, this transformer is given, at expansion time, a syntax object corresponding to the entire pattern (including @racket[id]). The pattern is replaced with the result of the transformer. -A transformer produced by a second @racket[proc-expr] subexpression is +A transformer produced by a second @racket[proc-expr] sub-expression is used when @racket[id] is used in an expression context. Using the second @racket[proc-expr], @racket[id] can be given meaning both inside and outside patterns.} diff --git a/collects/scribblings/reference/numbers.scrbl b/collects/scribblings/reference/numbers.scrbl index 18ae95f203..41ad7d2d21 100644 --- a/collects/scribblings/reference/numbers.scrbl +++ b/collects/scribblings/reference/numbers.scrbl @@ -479,7 +479,7 @@ Among the real numbers within @racket[(abs tolerance)] of @racket[x], @defproc[(>= [x real?] [y real?] ...+) boolean?]{ Returns @racket[#t] - if the arguments in the given order are in non-increasing, + if the arguments in the given order are non-increasing, @racket[#f] otherwise. @mz-examples[(>= 1 1) (>= 1 2 1)]} diff --git a/collects/scribblings/reference/pairs.scrbl b/collects/scribblings/reference/pairs.scrbl index 48288b0c51..28394090a8 100644 --- a/collects/scribblings/reference/pairs.scrbl +++ b/collects/scribblings/reference/pairs.scrbl @@ -482,7 +482,7 @@ Returns @scheme[(remove* v-lst lst eqv?)]. Returns a list sorted according to the @scheme[less-than?] procedure, which takes two elements of @scheme[lst] and returns a true value if - the first is less than (i.e., should be sorted earlier) the + the first is less (i.e., should be sorted earlier) than the second. The sort is stable; if two elements of @scheme[lst] are ``equal'' diff --git a/collects/scribblings/reference/pipes.scrbl b/collects/scribblings/reference/pipes.scrbl index 40c32bd457..c0ed194e7f 100644 --- a/collects/scribblings/reference/pipes.scrbl +++ b/collects/scribblings/reference/pipes.scrbl @@ -27,7 +27,7 @@ input port makes more space available. (Peeks effectively extend the port's capacity until the peeked bytes are read.) The optional @racket[input-name] and @racket[output-name] are used -as the names for the returned input and out ports, respectively.} +as the names for the returned input and output ports, respectively.} @defproc[(pipe-content-length [pipe-port port?]) exact-nonnegative-integer?]{ diff --git a/collects/scribblings/reference/places.scrbl b/collects/scribblings/reference/places.scrbl index 451a05af13..3e2c73372f 100644 --- a/collects/scribblings/reference/places.scrbl +++ b/collects/scribblings/reference/places.scrbl @@ -120,22 +120,22 @@ racket @defproc[(place-channel) (values place-channel? place-channel?)]{ - Returns two @tech{place channels}. Data send through the first - channel can be received through the second channel, and data send + Returns two @tech{place channels}. Data sent through the first + channel can be received through the second channel, and data sent through the second channel can be received from the first. Typically, one place channel is used by the current @tech{place} to send messages to a destination @tech{place}; the other place channel - us sent to the destination @tech{place} (via an existing @tech{place + is sent to the destination @tech{place} (via an existing @tech{place channel}). } @defproc[(place-channel-send [pch place-channel?] [v any/c]) void]{ - Sends a message @racket[v] on channel @racket[pch]. + Sends an immutable message @racket[v] on channel @racket[pch]. } @defproc[(place-channel-recv [pch place-channel?]) any/c]{ - Returns a message received on channel @racket[pch]. + Returns an immutable message received on channel @racket[pch]. } @defproc[(place-channel-send/recv [pch place-channel?] [v any/c]) void]{ diff --git a/collects/scribblings/reference/port-buffers.scrbl b/collects/scribblings/reference/port-buffers.scrbl index 4e39db700b..2ef01902ac 100644 --- a/collects/scribblings/reference/port-buffers.scrbl +++ b/collects/scribblings/reference/port-buffers.scrbl @@ -8,7 +8,7 @@ internally buffered: @itemize[ - @item{An input port is typically block buffered by default, which + @item{An input port is typically block-buffered by default, which means that on any read, the buffer is filled with immediately-available bytes to speed up future reads. Thus, if a file is modified between a pair of reads to the file, the @@ -16,8 +16,8 @@ internally buffered: @scheme[file-position] to set an input port's file position flushes its buffer.} - @item{And output port is typically block buffered by default, though - a terminal output port is line buffered, and the initial error + @item{An output port is typically block-buffered by default, though + a terminal output port is line-buffered, and the initial error output port is unbuffered. An output buffer is filled with a sequence of written bytes to be committed as a group, either when the buffer is full (in block mode), when a newline is @@ -44,7 +44,7 @@ buffered bytes, but no further bytes are read. In addition, the initial current output and error ports are automatically flushed when @scheme[read], @scheme[read-line], -@scheme[read-bytes], @scheme[read-string], etc. are performed on the +@scheme[read-bytes], @scheme[read-string], etc., are performed on the initial standard input port; more precisely, flushing is performed by the default port read handler (see @scheme[port-read-handler]). @@ -87,13 +87,13 @@ been read from that port if the position is known (see @secref["linecol"]), otherwise the @exnraise[exn:fail:filesystem]. For @tech{file-stream ports} and string ports, the position-setting -variants sets the read/write position to @scheme[pos] relative to the +variant sets the read/write position to @scheme[pos] relative to the beginning of the file/string if @scheme[pos] is a number, or to the current end of the file/string if @scheme[pos] is @scheme[eof]. In position-setting mode, @scheme[file-position] raises the @scheme[exn:fail:contract] exception for port kinds other than file-stream and string ports. Furthermore, not all @tech{file-stream -ports} support setting the position; f @scheme[file-position] is +ports} support setting the position; if @scheme[file-position] is called with a position argument on such a @tech{file-stream port}, the @exnraise[exn:fail:filesystem]. diff --git a/collects/scribblings/reference/port-lib.scrbl b/collects/scribblings/reference/port-lib.scrbl index 470e55d128..dd2504bcb1 100644 --- a/collects/scribblings/reference/port-lib.scrbl +++ b/collects/scribblings/reference/port-lib.scrbl @@ -72,7 +72,7 @@ lines like @racket[read-bytes-line]. [#:separator separator any/c #"\n"]) void?]{ -Use @racket[display] to each each element of @racket[lst] to @racket[out], adding +Uses @racket[display] on each element of @racket[lst] to @racket[out], adding @racket[separator] after each element.} @defproc[(call-with-output-string [proc (output-port? . -> . any)]) string?]{ @@ -90,7 +90,7 @@ accumulated data.} @defproc[(call-with-output-bytes [proc (output-port? . -> . any)]) bytes?]{ -Like @racket[call-with-output-string], but returns accumulated results +Like @racket[call-with-output-string], but returns the accumulated result in a @tech{byte string} instead of a string. Furthermore, the port's content is emptied when @racket[call-with-output-bytes] returns, so that if control jumps back into @racket[proc] and returns a second @@ -238,7 +238,7 @@ procedure, so it can be an integer or any result from Returns a port whose content is drawn from @racket[in], but where an end-of-file is reported after @racket[limit] bytes (and non-byte -special values) are read. If @racket[close-orig?] is true, then the +special values) have been read. If @racket[close-orig?] is true, then the original port is closed if the returned port is closed. Bytes are consumed from @racket[in] only when they are consumed from @@ -278,7 +278,7 @@ determine the names of the result ports.} Accepts two input ports and returns a new input port. The new port merges the data from two original ports, so data can be read from the -new port whenever it is available from either original port. The data +new port whenever it is available from either of the two original ports. The data from the original ports are interleaved. When an end-of-file has been read from an original port, it no longer contributes characters to the new port. After an end-of-file has been read from both original ports, @@ -396,14 +396,14 @@ incomplete encoding sequence.)} Produces an output port that directs bytes to @racket[out], but converts its byte stream using @racket[(bytes-open-converter "UTF-8" encoding-str)]. In addition, if @racket[newline-bytes] is not -@racket[#f], then byets written to the port that are the UTF-8 +@racket[#f], then bytes written to the port that are the UTF-8 encoding of @racket["\n"] are first converted to @racket[newline-bytes] (before applying the convert from UTF-8 to @racket[encoding-str]). If @racket[error-bytes] is provided and not @racket[#f], then the -given byte sequence is used in place of bytes send to the output port -that trigger conversion errors. Otherwise, @racket[enc-error] is +given byte sequence is used in place of bytes that have been sent to the output port +and that trigger conversion errors. Otherwise, @racket[enc-error] is called, which must raise an exception. If @racket[close?] is true, then closing the result output port also @@ -506,7 +506,7 @@ Like @racket[relocate-input-port], but for output ports.} Like @racket[relocate-input-port], except that arbitrary position information can be produced (when line counting is enabled) via -@racket[get-location], which used as for @racket[make-input-port]. If +@racket[get-location], which is used as for @racket[make-input-port]. If @racket[get-location] is @racket[#f], then the port counts lines in the usual way starting from @racket[init-pos], independent of locations reported by @racket[in]. @@ -572,13 +572,13 @@ closes @racket[in].} [close? any/c #t]) input-port?]{ -Produces an input port that that is equivalent to @racket[in], except +Produces an input port that is equivalent to @racket[in], except that when @racket[in] produces a procedure to access a special value, @racket[proc] is applied to the procedure to allow the special value to be replaced with an alternative. The @racket[proc] is called with the special-value procedure and the byte string that was given to the port's read or peek function (see @racket[make-input-port]), and the -result is used as te read or peek function's result. The +result is used as the read or peek function's result. The @racket[proc] can modify the byte string to substitute a byte for the special value, but the byte string is guaranteed only to hold at least one byte. @@ -593,7 +593,7 @@ closes @racket[in].} @defproc[(eof-evt [in input-port?]) evt?]{ -Returns a @tech{synchronizable event} is that is ready when +Returns a @tech{synchronizable event} that is ready when @racket[in] produces an @racket[eof]. If @racket[in] produces a mid-stream @racket[eof], the @racket[eof] is consumed by the event only if the event is chosen in a synchronization.} @@ -602,12 +602,12 @@ only if the event is chosen in a synchronization.} @defproc[(read-bytes-evt [k exact-nonnegative-integer?] [in input-port?]) evt?]{ -Returns a @tech{synchronizable event} is that is ready when @racket[k] +Returns a @tech{synchronizable event} that is ready when @racket[k] bytes can be read from @racket[in], or when an end-of-file is encountered in @racket[in]. If @racket[k] is @racket[0], then the event is ready immediately with @racket[""]. For non-zero @racket[k], if no bytes are available before an end-of-file, the event's result is -@racket[eof]. Otherwise the event's result is a byte string of up to +@racket[eof]. Otherwise, the event's result is a byte string of up to @racket[k] bytes, which contains as many bytes as are available (up to @racket[k]) before an available end-of-file. (The result is a byte string on less than @racket[k] bytes only when an end-of-file is @@ -671,7 +671,7 @@ a byte string.} evt?]{ Returns a @tech{synchronizable event} that is ready when a line of -characters or end-of-file can be read from @racket[inport]. The +characters or end-of-file can be read from @racket[in]. The meaning of @racket[mode] is the same as for @racket[read-line]. The event result is the read line of characters (not including the line separator). @@ -704,7 +704,7 @@ Like the @racket[read-...-evt] functions, but for peeking. The @racket[progress] indicates an event that effectively cancels the peek (so that the event never becomes ready). The @racket[progress] argument can be @racket[#f], in which case the event is never -cancelled.} +canceled.} @defproc[(regexp-match-evt [pattern (or/c string? bytes? regexp? byte-regexp?)] @@ -741,18 +741,18 @@ treated like @racket[eof].} @defproc[(convert-stream [from-encoding string?] [in input-port?] - [from-encoding string?] + [to-encoding string?] [out output-port?]) void?]{ Reads data from @racket[in], converts it using -@racket[(bytes-open-converter from-encoding-string -to-encoding-string)] and writes the converted bytes to +@racket[(bytes-open-converter from-encoding +to-encoding)] and writes the converted bytes to @racket[out]. The @racket[convert-stream] procedure returns after reaching @racket[eof] in @racket[in]. If opening the converter fails, the @exnraise[exn:fail]. Similarly, if -a conversion error occurs at any point while reading @racket[in], then +a conversion error occurs at any point while reading from @racket[in], then @exnraise[exn:fail].} @@ -774,7 +774,7 @@ written to every @racket[out]. The different @racket[out]s block output to each other, because each block of data read from @racket[in] is written completely to one @racket[out] before moving to the next @racket[out]. The @racket[out]s are written in the provided order, so -non-blocking ports (e.g., to a file) should be placed first in the +non-blocking ports (e.g., file output ports) should be placed first in the argument list.} @close-eval[port-eval] diff --git a/collects/scribblings/reference/port-line-counting.scrbl b/collects/scribblings/reference/port-line-counting.scrbl index 334f41ac78..acdff66242 100644 --- a/collects/scribblings/reference/port-line-counting.scrbl +++ b/collects/scribblings/reference/port-line-counting.scrbl @@ -25,7 +25,7 @@ return-linefeed combinations as a line terminator and as a single position (on all platforms). Each tab advances the column count to one before the next multiple of @math{8}. When a sequence of bytes in the range 128 to 253 forms a UTF-8 encoding of a character, the -position/column is incremented is incremented once for each byte, and +position/column is incremented once for each byte, and then decremented appropriately when a complete encoding sequence is discovered. See also @secref["ports"] for more information on UTF-8 decoding for ports. @@ -64,7 +64,7 @@ be disabled for a port after it is enabled.} Returns three values: an integer or @racket[#f] for the line number of the next read/written item, an integer or @racket[#f] for the next item's column, and an integer or @racket[#f] for the next item's -position. The next column and position normally increases as bytes are +position. The next column and position normally increase as bytes are read from or written to the port, but if line/character counting is enabled for @racket[port], the column and position results can decrease after reading or writing a byte that ends a UTF-8 encoding diff --git a/collects/scribblings/reference/port-procs.scrbl b/collects/scribblings/reference/port-procs.scrbl index e1ec4d2adf..b461a66992 100644 --- a/collects/scribblings/reference/port-procs.scrbl +++ b/collects/scribblings/reference/port-procs.scrbl @@ -53,5 +53,5 @@ terminal, @scheme[#f] otherwise.} @defthing[eof eof-object?]{A value (distinct from all other values) that represents an end-of-file.} -@defproc[(eof-object? [a any/c]) boolean?]{Returns @scheme[#t] is +@defproc[(eof-object? [a any/c]) boolean?]{Returns @scheme[#t] if @scheme[v] is @scheme[eof], @scheme[#f] otherwise.} diff --git a/collects/scribblings/reference/ports.scrbl b/collects/scribblings/reference/ports.scrbl index fcf8803761..41d8788db7 100644 --- a/collects/scribblings/reference/ports.scrbl +++ b/collects/scribblings/reference/ports.scrbl @@ -8,7 +8,7 @@ a character-based operation, the port's bytes are decoded; see @secref["encodings"]. When a port corresponds to a file, network connection, or some other -system resource, is must be explicitly closed via +system resource, it must be explicitly closed via @scheme[close-input-port] or @scheme[close-output-port] (or indirectly via @scheme[custodian-shutdown-all]) to release low-level resources associated with the port. For any kind of port, after it is closed, diff --git a/collects/scribblings/reference/pretty-print.scrbl b/collects/scribblings/reference/pretty-print.scrbl index bc6c1692e2..ed17101a30 100644 --- a/collects/scribblings/reference/pretty-print.scrbl +++ b/collects/scribblings/reference/pretty-print.scrbl @@ -24,7 +24,7 @@ In addition to the parameters defined in this section, @scheme[print-as-expression] parameters. The pretty printer detects structures that have the -@scheme[prop:custom-write] property and it calls the corresponding +@scheme[prop:custom-write] property and calls the corresponding custom-write procedure. The custom-write procedure can check the parameter @scheme[pretty-printing] to cooperate with the pretty-printer. Recursive printing to the port automatically uses @@ -88,7 +88,7 @@ the output.} Parameter that controls the default depth for recursive pretty printing. Printing to @scheme[depth] means that elements nested more deeply than @scheme[depth] are replaced with ``...''; in particular, a -depth of 0 indicates that only simple values are printed. A depth of +depth of @racket[0] indicates that only simple values are printed. A depth of @scheme[#f] (the default) allows printing to arbitrary depths.} @@ -122,7 +122,7 @@ printed with a leading @litchar{#i}. The initial value is @scheme[#f].} @defboolparam[pretty-print-abbreviate-read-macros abbrev?]{ A parameter that controls whether or not @schemeidfont{quote}, -@schemeidfont{unquote}, @schemeidfont{unquote-splicing}, @|etc| are +@schemeidfont{unquote}, @schemeidfont{unquote-splicing}, @|etc|, are abbreviated with @litchar{'}, @litchar{,}, @litchar[",@"], etc. By default, the abbreviations are enabled. @@ -153,7 +153,7 @@ Creates a new style table by extending an existing corresponding symbol of @scheme[symbol-list] in the new table. The @scheme[symbol-list] and @scheme[like-symbol-list] lists must have the same length. The @scheme[style-table] argument can be @scheme[#f], in -which case with default mappings are used for the original table (see +which case the default mappings are used from the original table (see below). The style mapping for a symbol controls the way that whitespace is @@ -193,12 +193,12 @@ A parameter that controls remapping for styles and for the determination of the reader shorthands. This procedure is -called with each subexpression that appears as the first element in a +called with each sub-expression that appears as the first element in a sequence. If it returns a symbol, the style table is used, as if that symbol were at the head of the sequence. If it returns @scheme[#f], the style table is treated normally. -Similarly, when determining whether or not to abbreviate reader macros, -the parameter is consulted. +Similarly, when determining whether to abbreviate reader macros, +this parameter is consulted. } @@ -234,8 +234,8 @@ beginning of the new line. The @scheme[proc] procedure is called before any characters are printed with @scheme[0] as the line number and @scheme[0] as the old -line length; @scheme[proc] is called after the last character for a -value is printed with @scheme[#f] as the line number and with the +line length; @scheme[proc] is called after the last character of a +value has been printed with @scheme[#f] as the line number and with the length of the last line. Whenever the pretty-printer starts a new line, @scheme[proc] is called with the new line's number (where the first new line is numbered @scheme[1]) and the just-finished line's @@ -278,7 +278,7 @@ called to actually print the value (see @scheme[pretty-print-print-hook]). The sizing hook receives three arguments. The first argument is the -value to print. The second argument is a Boolean: @scheme[#t] for +value to print. The second argument is a boolean: @scheme[#t] for printing like @scheme[display] and @scheme[#f] for printing like @scheme[write]. The third argument is the destination port; the port is the one supplied to @scheme[pretty-print] or @@ -356,7 +356,7 @@ decremented to leave room for a terminator. The @scheme[overflow-thunk] procedure is called if more than @scheme[width] items are printed to the port or if a newline is printed to the port via @racket[pretty-print-newline]; it can escape from the -recursive print through a continuation as a short cut, but +recursive print through a continuation as a shortcut, but @scheme[overflow-thunk] can also return, in which case it is called every time afterward that additional output is written to the port. diff --git a/collects/scribblings/reference/printer.scrbl b/collects/scribblings/reference/printer.scrbl index b4523d3184..2a2f4209c3 100644 --- a/collects/scribblings/reference/printer.scrbl +++ b/collects/scribblings/reference/printer.scrbl @@ -12,8 +12,8 @@ The Racket printer supports three modes: using @racket[read] on the output produces a value that is @racket[equal?] to the printed value;} - @item{@racket[display] mode prints core datatypes is a form in a more - ``end-user'' style rather than ``programmer' style; for + @item{@racket[display] mode prints core datatypes in a more + ``end-user'' style rather than ``programmer'' style; for example, a string @racket[display]s as its content characters without surrounding @litchar{"}s or escapes;} @@ -53,7 +53,7 @@ automatically. With the exception of displaying byte strings, printing is defined in terms of Unicode characters; see @secref["ports"] for information -on how a character stream is written to an port's underlying byte +on how a character stream is written to a port's underlying byte stream. @@ -62,7 +62,7 @@ stream. Symbols containing spaces or special characters @scheme[write] using escaping @litchar{\} and quoting @litchar{|}s. When the @scheme[read-case-sensitive] parameter is set to @scheme[#f], then -symbols containing uppercase characters also use escaping escaping +symbols containing uppercase characters also use escaping @litchar{\} and quoting @litchar{|}s. In addition, symbols are quoted with @litchar{|}s or leading @litchar{\} when they would otherwise print the same as a numerical constant or as a delimited @@ -70,7 +70,7 @@ otherwise print the same as a numerical constant or as a delimited When @scheme[read-accept-bar-quote] is @scheme[#t], @litchar{|}s are used in printing when one @litchar{|} at the beginning and one -@litchar{|} at the end suffices to correctly print the +@litchar{|} at the end suffice to correctly print the symbol. Otherwise, @litchar{\}s are always used to escape special characters, instead of quoting them with @litchar{|}s. @@ -80,7 +80,7 @@ special characters: @t{ @hspace[2] @litchar{(} @litchar{)} @litchar{[} @litchar{]} - @litchar{[} @litchar{]} + @litchar["}"] @litchar["}"] @litchar{"} @litchar{,} @litchar{'} @litchar{`} @litchar{;} @litchar{\} } @@ -93,7 +93,7 @@ characters. That is, the display form of a symbol is the same as the display form of @scheme[symbol->string] applied to the symbol. Symbols @scheme[print] the same as they @scheme[write], unless -@scheme[print-as-expression] is set to @scheme[#t] and the current +@scheme[print-as-expression] is set to @scheme[#t] (as is the default) and the current @tech{quoting depth} is @scheme[0]. In that case, the symbol's @scheme[print]ed form is prefixed with @litchar{'}. For the purposes of printing enclosing datatypes, a symbol is @tech{quotable}. @@ -121,11 +121,11 @@ does not start with @scheme[0]. A positive, exact, real, non-integer number prints as @nonterm{m}@litchar{/}@nonterm{n}, where @nonterm{m} and @nonterm{n} -are the printed forms of the number's numerators and denominator (as +are the printed forms of the number's numerator and denominator (as determined by @scheme[numerator] and @scheme[denominator]). A negative @tech{exact number} prints with a @litchar{-} prefix on the -printed form of its exact negation. +printed form of the number's exact negation. @section{Printing Booleans} @@ -160,7 +160,7 @@ If @scheme[print-reader-abbreviations] is set to @scheme[#t], then pair printing in @scheme[write] mode is adjusted in the case of a pair that starts a two-element list whose first element is @scheme['quote], @scheme['quasiquote], @scheme['unquote], @scheme['unquote-splicing], -@scheme['syntax], @scheme['quasisyntax], @scheme['unsyntax], +@scheme['syntax], @scheme['quasisyntax], @scheme['unsyntax], or @scheme['unsyntax-splicing]. In that case, the pair is printed with the corresponding reader syntax: @litchar{'}, @litchar{`}, @litchar{,}, @litchar[",@"], @litchar{#'}, @litchar{#`}, @litchar{#,}, @@ -173,8 +173,8 @@ including the tail as two elements of the enclosing list. The printed form of a pair is the same in both @scheme[write] and @scheme[display] modes, except as the printed form of the pair's @scheme[car] and @scheme[cdr] vary with the mode. The @scheme[print] -form is also the same is @scheme[print-as-expression] is @scheme[#f] -or when the quoting depth is @scheme[1]. +form is also the same if @scheme[print-as-expression] is @scheme[#f] +or the quoting depth is @scheme[1]. For @scheme[print] mode when @scheme[print-as-expression] is @scheme[#t] and the @tech{quoting depth} is @scheme[0], then the empty @@ -198,7 +198,7 @@ same as pairs for @scheme[write] and @scheme[display], except that @litchar["{"] and @litchar["}"] are used instead of @litchar{(} and @litchar{)}. Note that the reader treats @litchar["{"]...@litchar["}"] and @litchar{(}...@litchar{)} equivalently on input, creating -immutable pairs in both cases. Mutable in @scheme[print] mode with +immutable pairs in both cases. Mutable pairs in @scheme[print] mode with @scheme[print-as-expression] as @scheme[#f] or a @tech{quoting depth} of @scheme[1] also use @litchar["{"] and @litchar["}"]. In @scheme[print] mode with @scheme[print-as-expression] as @scheme[#t] @@ -208,8 +208,8 @@ and a @tech{quoting depth} of @scheme[0], a mutable pair prints as closing @litchar{)}. If the @scheme[print-pair-curly-braces] parameter is set to -@scheme[#t], then pairs print using @litchar["{"] and @litchar["}"] in -when not using @scheme[print] mode with @scheme[print-as-expression] a +@scheme[#t], then pairs print using @litchar["{"] and @litchar["}"] +when not using @scheme[print] mode with @scheme[print-as-expression] as @scheme[#t] and a @tech{quoting depth} of @scheme[0]. If the @scheme[print-mpair-curly-braces] parameter is set to @scheme[#f], then mutable pairs print using @litchar{(} and @litchar{)} in that @@ -242,8 +242,8 @@ All byte strings @scheme[display] as their literal byte sequence; this byte sequence may not be a valid UTF-8 encoding, so it may not correspond to a sequence of characters. -The @scheme[write] or @scheme[print] form a byte string starts with @litchar{#"} and -ends with another @litchar{"}. Between the @litchar{"}s, each byte is +The @scheme[write] or @scheme[print] form of a byte string starts with @litchar{#"} and +ends with a @litchar{"}. Between the @litchar{"}s, each byte is written using the corresponding ASCII decoding if the byte is between 0 and 127 and the character is graphic or blank (according to @scheme[char-graphic?] and @scheme[char-blank?]). Otherwise, the byte @@ -288,7 +288,7 @@ for which the structure is an instance: @item{If the structure type is a @tech{prefab} structure type, then it prints in @scheme[write] or @scheme[display] mode using @litchar{#s(} followed by the @tech{prefab} structure type key, - then the printed form each field in the structure, and then + then the printed form of each field in the structure, and then @litchar{)}. In @scheme[print] mode when @scheme[print-as-expression] is set @@ -340,7 +340,7 @@ for which the structure is an instance: depth of @scheme[1].} @item{If the structure's type is transparent or if any ancestor is - transparent (i.e,. @scheme[struct?] on the instance produces + transparent (i.e., @scheme[struct?] on the instance produces @scheme[#t]), then the structure prints as the vector produced by @scheme[struct->vector] in @scheme[display] mode, in @scheme[write] mode, or in @scheme[print] mode when @@ -349,8 +349,8 @@ for which the structure is an instance: In @scheme[print] mode with @scheme[print-as-expression] as @scheme[#t] and a @tech{quoting depth} of @scheme[0], the - structure content is printed with a @litchar{(} followed by the - list is the structure's type name (as determined by + structure content is printed with a @litchar{(} followed by + the structure's type name (as determined by @scheme[object-name]) in @scheme[write] mode; the remaining elements are @scheme[print]ed at @tech{quoting depth} @scheme[0] and separated by a space, and finally a closing @@ -376,15 +376,15 @@ When the @scheme[print-hash-table] parameter is set to @scheme[#t], in @scheme[write] and @scheme[display] modes, a hash table prints starting with @litchar{#hash(}, @litchar{#hasheqv(}, or @litchar{#hasheq(} for a table using @scheme[equal?], @scheme[eqv?], -or @scheme[eq?] key comparisons, respectively. After this prefix, each +or @scheme[eq?] key comparisons, respectively. After the prefix, each key--value mapping is shown as @litchar{(}, the printed form of a key, a space, @litchar{.}, a space, the printed form the corresponding value, and @litchar{)}, with an additional space if the key--value -pair is not the last to be printed. After all key-value pairs, the +pair is not the last to be printed. After all key--value pairs, the printed form completes with @litchar{)}. In @scheme[print] mode when @scheme[print-as-expression] is -@scheme[#f] or the @tech{quoting depth} is @scheme[1], the printed for +@scheme[#f] or the @tech{quoting depth} is @scheme[1], the printed form is the same as for @scheme[write]. Otherwise, if the hash table's keys and values are all @tech{quotable}, the table prints with a @litchar{'} prefix, and the table's key and values are @racket[print]ed @@ -404,7 +404,7 @@ hash table prints as @litchar{#} and counts as @tech{quotable}. When the @scheme[print-box] parameter is set to @scheme[#t], a box prints as @litchar{#&} followed by the printed form of its content in -@scheme[write] mode, @scheme[display], or @scheme[print] mode when +@scheme[write], @scheme[display], or @scheme[print] mode when @scheme[print-as-expression] is @scheme[#f] or the @tech{quoting depth} is @scheme[1]. @@ -426,12 +426,12 @@ Characters with the special names described in @secref["parse-character"] @scheme[write] and @scheme[print] using the same name. (Some characters have multiple names; the @scheme[#\newline] and @scheme[#\nul] names are used instead of -@scheme[#\linefeed] and @scheme[#\null]). Other graphic characters +@schemevalfont{#\linefeed} and @schemevalfont{#\null}.) Other graphic characters (according to @scheme[char-graphic?]) @scheme[write] as @litchar{#\} followed by the single character, and all others characters are written in @scheme[#\u] notation with four digits or @scheme[#\U] notation with eight digits (using the latter only if the character -value it does not fit in four digits). +value does not fit in four digits). All characters @scheme[display] directly as themselves (i.e., a single character). @@ -443,10 +443,10 @@ For the purposes of printing enclosing datatypes, a character is @section{Printing Keywords} Keywords @scheme[write], @scheme[print], and @scheme[display] the same -as symbols, except (see @secref["print-symbol"]) with a leading +as symbols (see @secref["print-symbol"]) except with a leading @litchar{#:} (after any @litchar{'} prefix added in @scheme[print] -mode), and without special handing for an initial @litchar{#} or when -the printed form would matches a number or a delimited @litchar{.} +mode), and without special handling for an initial @litchar{#} or when +the printed form would match a number or a delimited @litchar{.} (since @litchar{#:} distinguishes the keyword). For the purposes of printing enclosing datatypes, a keyword is @@ -480,7 +480,7 @@ information when converting a path to a string. For a path that is intended to be re-read on the same platform, a byte string is probably the right choice, since it preserves information in an unportable way. Paths do not print in a readable way so that programmers are not -mislead into thinking that either choice is always appropriate. +misled into thinking that either choice is always appropriate. @section[#:tag "print-unreadable"]{Printing Unreadable Values} @@ -501,13 +501,13 @@ unreadably nevertheless counts as @tech{quotable}. Compiled code as produced by @racket[compile] prints using @litchar{#~}. Compiled code printed with @litchar{#~} is essentially -assembly code for Racket, and reading such an form produces a compiled +assembly code for Racket, and reading such a form produces a compiled form when the @racket[read-accept-compiled] parameter is set to @racket[#t]. When a compiled form contains syntax object constants, the @litchar{#~}-marshaled form drops source-location information and -properties (@secref["stxprops"]) for the @tech{syntax objects}. +properties (see @secref["stxprops"]) for the @tech{syntax objects}. Compiled code parsed from @litchar{#~} may contain references to unexported or protected bindings from a module. At read time, such diff --git a/collects/scribblings/reference/prop-port.scrbl b/collects/scribblings/reference/prop-port.scrbl index f950779982..ab1a633e35 100644 --- a/collects/scribblings/reference/prop-port.scrbl +++ b/collects/scribblings/reference/prop-port.scrbl @@ -15,15 +15,15 @@ Each property value can be either of the following: @itemize[ @item{An input port (for @scheme[prop:input-port]) or output port - (for @scheme[prop:input-port]): In this case, using the structure - as port is equivalent to using the given one.} + (for @scheme[prop:output-port]): In this case, using the structure + as port is equivalent to using the given input or output port.} @item{An exact, non-negative integer between @scheme[0] (inclusive) and - number of non-automatic fields in the structure type (exclusive, not + the number of non-automatic fields in the structure type (exclusive, not counting supertype fields): The integer identifies a field in the structure, and the field must be designated as immutable. If the field contains an input port (for @scheme[prop:input-port]) or - output port (for @scheme[prop:input-port]), the port is used. + output port (for @scheme[prop:output-port]), the port is used. Otherwise, an empty string input port is used for @scheme[prop:input-port], and a port that discards all data is used for @scheme[prop:output-port].} diff --git a/collects/scribblings/reference/read.scrbl b/collects/scribblings/reference/read.scrbl index 3e63ed48b3..e9c83a6a67 100644 --- a/collects/scribblings/reference/read.scrbl +++ b/collects/scribblings/reference/read.scrbl @@ -84,7 +84,7 @@ Analogous to calling @racket[read/recursive], but the resulting value encapsulates S-expression structure with source-location information. As with @racket[read/recursive], when @racket[read-syntax/recursive] is used within the dynamic extent of -@racket[read-syntax], the result of from +@racket[read-syntax], the result from @racket[read-syntax/recursive] is either a special-comment value, end-of-file, or opaque graph-structure placeholder (not a syntax object). The placeholder can be embedded in an S-expression or syntax @@ -109,7 +109,7 @@ See @secref["readtables"] for an extended example that uses [fail-thunk (-> any) (lambda () (error ...))]) (any/c any/c . -> . any)]{ -Reads @racket[in] in the same way as @racket[read], but stopping as +Reads from @racket[in] in the same way as @racket[read], but stopping as soon as a @tech{reader language} (or its absence) is determined. A @deftech{reader language} is specified by @litchar{#lang} or @@ -124,7 +124,7 @@ or @litchar{#!}. When it finds a @litchar{#lang} or @litchar{#!} specification, instead of dispatching to a @racketidfont{read} or @racketidfont{read-syntax} -form as @racket[read] and @racket[read-syntax] do, +function as @racket[read] and @racket[read-syntax] do, @racket[read-language] dispatches to a @racketidfont{get-info} function (if any) exported by the same module. The result of the @racketidfont{get-info} function is the result of @@ -278,7 +278,7 @@ is @racket[#t]. Even when parsing is delayed, compiled code is loaded into memory. If the @as-index{@envvar{PLT_DELAY_FROM_ZO}} environment variable is set -(to any value) on start up, however, even loading from disk is +(to any value) on start-up, however, even loading from disk is delayed. If the file at @tech{path} changes before the delayed code or syntax object is demanded, the read-on-demand most likely will encounter garbage, leading to an exception.} diff --git a/collects/scribblings/reference/reader.scrbl b/collects/scribblings/reference/reader.scrbl index b488369ecf..15c65ce5cf 100644 --- a/collects/scribblings/reference/reader.scrbl +++ b/collects/scribblings/reference/reader.scrbl @@ -33,7 +33,7 @@ around the sort of datum that @racket[read] mode would produce. In the case of pairs, vectors, and boxes, the content is also wrapped recursively as a syntax object. Unless specified otherwise, this section describes the reader's behavior in @racket[read] mode, -and @racket[read-syntax] mode does the same modulo wrapping the final +and @racket[read-syntax] mode does the same modulo wrapping of the final result. Reading is defined in terms of Unicode characters; see @@ -48,7 +48,7 @@ characters are @defterm{delimiters}: @t{ @hspace[2] @ilitchar{(} @ilitchar{)} @ilitchar{[} @ilitchar{]} - @ilitchar["["] @ilitchar["]"] + @ilitchar["{"] @ilitchar["}"] @ilitchar{"} @ilitchar{,} @ilitchar{'} @ilitchar{`} @ilitchar{;} } @@ -64,7 +64,7 @@ characters play special roles: follow; see below.} @item{@as-index{@litchar{|}} starts a subsequence of characters to - be included verbatim in the delimited sequence (i.e,. they are + be included verbatim in the delimited sequence (i.e., they are never treated as delimiters, and they are not case-folded when case-insensitivity is enabled); the subsequence is terminated by another @litchar{|}, and neither the initial nor @@ -92,7 +92,7 @@ on the next character or characters in the input stream as follows: @dispatch[@litchar{"}]{starts a string; see @secref["parse-string"]} @dispatch[@litchar{'}]{starts a quote; see @secref["parse-quote"]} @dispatch[@litchar{`}]{starts a quasiquote; see @secref["parse-quote"]} - @dispatch[@litchar{,}]{starts an [splicing] unquote; see @secref["parse-quote"]} + @dispatch[@litchar{,}]{starts a [splicing] unquote; see @secref["parse-quote"]} @dispatch[@litchar{;}]{starts a line comment; see @secref["parse-comment"]} @@ -121,7 +121,7 @@ on the next character or characters in the input stream as follows: @dispatch[@litchar{#!/}]{starts a line comment; see @secref["parse-comment"]} @dispatch[@litchar{#!}]{may start a reader extension; see @secref["parse-reader"]} @dispatch[@litchar{#`}]{starts a syntax quasiquote; see @secref["parse-quote"]} - @dispatch[@litchar{#,}]{starts an syntax [splicing] unquote; see @secref["parse-quote"]} + @dispatch[@litchar{#,}]{starts a syntax [splicing] unquote; see @secref["parse-quote"]} @dispatch[@litchar{#~}]{starts compiled code; see @secref["print-compiled"]} @dispatch[@cilitchar{#i}]{starts a number; see @secref["parse-number"]} @@ -179,7 +179,7 @@ characters in the sequence that are not quoted by @litchar{|} or @litchar{#cI}, then it recursively reads the following datum in case-insensitive mode. If the reader encounters @as-index{@litchar{#cs}}, @litchar{#CS}, @litchar{#Cs}, or -@litchar{#cS}, then recursively reads the following datum in +@litchar{#cS}, then it recursively reads the following datum in case-sensitive mode. @reader-examples[#:symbols? #f @@ -226,9 +226,9 @@ matches the @nonterm{general-number@sub{2}}, @nonterm{general-number@sub{16}} grammar, respectively. An @nunterm{exponent-mark} in an inexact number serves both to specify -an exponent and specify a numerical precision. If single-precision +an exponent and to specify a numerical precision. If single-precision IEEE floating point is supported (see @secref["numbers"]), the marks -@litchar{f} and @litchar{s} specifies single-precision. Otherwise, or +@litchar{f} and @litchar{s} specify single-precision. Otherwise, or with any other mark, double-precision IEEE floating point is used. In addition, single- and double-precision specials are distinct; specials with the @litchar{.0} suffix, like @racket[-nan.0] are @@ -322,9 +322,9 @@ the recursive reads. If the reader finds two data between the matching parentheses that are separated by a delimited @litchar{.}, then it creates a pair. More generally, if it finds two or more data where the -last is preceded by a delimited @litchar{.}, then it constructs +last datum is preceded by a delimited @litchar{.}, then it constructs nested pairs: the next-to-last element is paired with the last, then -the third-to-last is paired with that pair, and so on. +the third-to-last datum is paired with that pair, and so on. If the reader finds three or more data between the matching parentheses, and if a pair of delimited @litchar{.}s surrounds any @@ -335,7 +335,7 @@ supports a kind of @as-index{infix} notation at the reader level. In @racket[read-syntax] mode, the recursive reads for the pair/list elements are themselves in @racket[read-syntax] mode, so that the -result is list or pair of syntax objects that it itself wrapped as a +result is a list or pair of syntax objects that is itself wrapped as a syntax object. If the reader constructs nested pairs because the input included a single delimited @litchar{.}, then only the innermost pair and outtermost pair are wrapped as syntax objects. Whether wrapping a @@ -363,10 +363,10 @@ being parsed, then the @exnraise[exn:fail:read]. ] If the @racket[read-square-bracket-as-paren] @tech{parameter} is set to -@racket[#f], then when then reader encounters @litchar{[} and -@litchar{]}, the @exnraise{exn:fail:read}. Similarly, If the +@racket[#f], then when the reader encounters @litchar{[} and +@litchar{]}, the @exnraise{exn:fail:read}. Similarly, if the @racket[read-curly-brace-as-paren] @tech{parameter} is set to @racket[#f], -then when then reader encounters @litchar["{"] and @litchar["}"], the +then when the reader encounters @litchar["{"] and @litchar["}"], the @exnraise{exn:fail:read}. If the @racket[read-accept-dot] @tech{parameter} is set to @@ -407,7 +407,7 @@ Within a string sequence, the following escape sequences are @item{@as-index{@litchar{\}@kleenerange[1 3]{@nonterm{digit@sub{8}}}}: Unicode for the octal number specified by @kleenerange[1 - 3]{digit@sub{8}} (i.e., 1 to 3 @nonterm{digit@sub{8}}s) where + 3]{digit@sub{8}} (i.e., 1 to 3 @nonterm{digit@sub{8}}s), where each @nonterm{digit@sub{8}} is @litchar{0}, @litchar{1}, @litchar{2}, @litchar{3}, @litchar{4}, @litchar{5}, @litchar{6}, or @litchar{7}. A longer form takes precedence @@ -441,7 +441,7 @@ Within a string sequence, the following escape sequences are @item{@as-index{@litchar{\}@nonterm{newline}}: elided, where @nonterm{newline} is either a linefeed, carriage return, or - carriage return--linefeed combination. This convetion allows + carriage return--linefeed combination. This convention allows single-line strings to span multiple lines in the source.} ] @@ -454,9 +454,9 @@ constant, the @exnraise[exn:fail:read]. @section-index["byte strings" "parsing"] A string constant preceded by @litchar{#} is parsed as a -byte-string. (That is, @as-index{@litchar{#"}} starts a byte-string +byte string. (That is, @as-index{@litchar{#"}} starts a byte-string literal.) See @secref["bytestrings"] for information on byte -strings. Byte string constants support the same escape sequences as +strings. Byte-string constants support the same escape sequences as character strings, except @litchar{\u} and @litchar{\U}. When the reader encounters @as-index{@litchar{#<<}}, it starts parsing a @@ -485,7 +485,7 @@ encountered before a terminating line, the @exnraise[exn:fail:read]. @section[#:tag "parse-quote"]{Reading Quotes} When the reader enounters @as-index{@litchar{'}}, it recursively -reads one datum, and forms a new list containing the symbol +reads one datum and forms a new list containing the symbol @racket['quote] and the following datum. This convention is mainly useful for reading Racket code, where @racket['s] can be used as a shorthand for @racket[(code:quote s)]. @@ -509,7 +509,7 @@ way. Longer prefixes take precedence over short ones: The @litchar{`}, @litchar{,}, and @litchar[",@"] forms are disabled when the @racket[read-accept-quasiquote] @tech{parameter} is set to -@racket[#f], in which case the @exnraise[exn:fail:read], instead. +@racket[#f], in which case the @exnraise[exn:fail:read] instead. @section[#:tag "parse-comment"]{Reading Comments} @@ -517,7 +517,7 @@ A @as-index{@litchar{;}} starts a line comment. When the reader encounters @litchar{;}, it skips past all characters until the next linefeed (ASCII 10), carriage return (ASCII 13), next-line (Unicode @racket[#x0085]), line-separator (Unicode @racket[#x2028]), -or line-separator (Unicode @racket[#x2028]) character. +or paragraph-separator (Unicode @racket[#x2029]) character. A @as-index{@litchar{#|}} starts a nestable block comment. When the reader encounters @litchar{#|}, it skips past all characters @@ -567,7 +567,7 @@ is used for all slots. In @racket[read-syntax] mode, each recursive read for the vector elements is also in @racket[read-syntax] mode, so that the wrapped -vector's elements are also wraped as syntax objects, and the vector is +vector's elements are also wrapped as syntax objects, and the vector is immutable. @reader-examples[ @@ -601,7 +601,7 @@ structure. In @racket[read-syntax] mode, the structure type must not have any mutable fields. The structure's elements are read in @racket[read-syntax] mode, so that the wrapped structure's elements -are also wraped as syntax objects. +are also wrapped as syntax objects. If the first structure element is not a valid @tech{prefab} structure type key, or if the number of provided fields is inconsistent with the @@ -614,7 +614,7 @@ A @as-index{@litchar{#hash}} starts an immutable hash-table constant with key matching based on @racket[equal?]. The characters after @litchar{hash} must parse as a list of pairs (see @secref["parse-pair"]) with a specific use of delimited @litchar{.}: -it must appear between the elements of each pair in the list, and +it must appear between the elements of each pair in the list and nowhere in the sequence of list elements. The first element of each pair is used as the key for a table entry, and the second element of each pair is the associated value. @@ -649,7 +649,7 @@ datum. In @racket[read-syntax] mode, the recursive read for the box content is also in @racket[read-syntax] mode, so that the wrapped box's -content is also wraped as a syntax object, and the box is immutable. +content is also wrapped as a syntax object, and the box is immutable. @reader-examples[ "#&17" @@ -742,7 +742,7 @@ as constructed by @racket[pregexp], @litchar{#rx#} as constructed by A @graph-defn[] tags the following datum for reference via @graph-ref[], which allows the reader to produce a datum that -have graph structure. +has graph structure. For a specific @graph-tag[] in a single read result, each @graph-ref[] reference is replaced by the datum read for the corresponding @@ -795,7 +795,7 @@ integer or @racket[#f]), column (non-negative exact integer or @racket[#f]), and position (positive exact integer or @racket[#f]) of the start of the @litchar{#reader} form. The input port is the one whose stream contained @litchar{#reader}, where the stream position is -immediately after the recursively-read module path. +immediately after the recursively read module path. The procedure should produce a datum result. If the result is a syntax object in @racket[read] mode, then it is converted to a datum @@ -824,9 +824,9 @@ external reading procedure is called. @guideintro["hash-languages"]{the creation languages for @hash-lang[]} -Finally, @as-index{@litchar{#!}} is a synonym for @litchar{#lang} +Finally, @as-index{@litchar{#!}} is an alias for @litchar{#lang} followed by a space when @litchar{#!} is followed by alphanumeric -ASCII, @litchar{+}, @litchar{-}, or @litchar{_}. Use of this synonym +ASCII, @litchar{+}, @litchar{-}, or @litchar{_}. Use of this alias is discouraged except as needed to construct programs that conform to certain grammars, such as that of R@superscript{6}RS @cite["Sperber07"]. diff --git a/collects/scribblings/reference/readtables.scrbl b/collects/scribblings/reference/readtables.scrbl index ef26826c87..15b49cde6d 100644 --- a/collects/scribblings/reference/readtables.scrbl +++ b/collects/scribblings/reference/readtables.scrbl @@ -50,7 +50,7 @@ readtable is ignored until the comment's terminating newline is discovered. Similarly, the readtable does not affect string parsing until a closing double-quote is found. Meanwhile, if a character is mapped to the default behavior of @litchar{(}, then it starts sequence -that is closed by any character that is mapped to a close parenthesis +that is closed by any character that is mapped to a closing parenthesis @litchar{)}. An apparent exception is that the default parsing of @litchar{|} quotes a symbol until a matching character is found, but the parser is simply using the character that started the quote; it @@ -130,7 +130,7 @@ The possible combinations for @racket[key], @racket[mode], and @item{@racket[(code:line #f (unsyntax @indexed-racket['non-terminating-macro]) _proc)] --- replaces the macro used to parse characters with no specific mapping: - i.e., characters (other than @litchar{#} or @litchar{|}) that can + i.e., the characters (other than @litchar{#} or @litchar{|}) that can start a symbol or number with the default readtable.} ] @@ -171,7 +171,7 @@ Produces information about the mappings in @racket[readtable] for @itemize[ - @item{either a character (mapping is to same behavior as the + @item{either a character (mapping to same behavior as the character in the default readtable), @racket['terminating-macro], or @racket['non-terminating-macro]; this result reports the main (i.e., non-@racket['dispatch-macro]) mapping for @racket[key]. When the result @@ -333,11 +333,11 @@ can be triggered by calls to @racket[read-honu], @racket[read-honu/recursive], @racket[read-honu-syntax], @racket[read-honu-syntax/recursive], @racket[read-char-or-special], or by the context of @racket[read-bytes-avail!], -@racket[read-bytes-avail!*], @racket[read-bytes-avail!], and +@racket[peek-bytes-avail!*], @racket[read-bytes-avail!], and @racket[peek-bytes-avail!*]. Optional arities for reader-macro and special-result procedures allow -them to distinguish reads via @racket[read], @|etc| from reads via +them to distinguish reads via @racket[read], @|etc|, from reads via @racket[read-syntax], @|etc| (where the source value is @racket[#f] and no other location information is available). @@ -365,7 +365,7 @@ Also, in either context, the result may be copied to prevent mutation to vectors or boxes before the read result is completed, and to support the construction of graphs with cycles. Mutable boxes, vectors, and @tech{prefab} structures are copied, along with any -pairs, boxes, vectors, pre prefab structures that lead to such mutable +pairs, boxes, vectors, prefab structures that lead to such mutable values, to placeholders produced by a recursive read (see @racket[read/recursive]), or to references of a shared value. Graph structure (including cycles) is preserved in the copy. @@ -376,7 +376,7 @@ structure (including cycles) is preserved in the copy. @defproc[(make-special-comment [v any/c]) special-comment?]{ Creates a special-comment value that encapsulates @racket[v]. The -@racket[read], @racket[read-syntax], @|etc| procedures treat values +@racket[read], @racket[read-syntax], @|etc|, procedures treat values constructed with @racket[make-special-comment] as delimiting whitespace when returned by a reader-extension procedure (see @secref["reader-procs"]).} @@ -390,5 +390,5 @@ Returns @racket[#t] if @racket[v] is the result of Returns the value encapsulated by the special-comment value @racket[sc]. This value is never used directly by a reader, but it -might be used by the context of a @racket[read-char-or-special], @|etc| +might be used by the context of a @racket[read-char-or-special], @|etc|, call that detects a special comment.} diff --git a/collects/scribblings/reference/regexps.scrbl b/collects/scribblings/reference/regexps.scrbl index 8b125ded20..15b9c362f4 100644 --- a/collects/scribblings/reference/regexps.scrbl +++ b/collects/scribblings/reference/regexps.scrbl @@ -275,7 +275,7 @@ The first [byte] string in a result list is the portion of earliest is found. Additional [byte] strings are returned in the list if @racket[pattern] -contains parenthesized sub-expressions (but not when the open +contains parenthesized sub-expressions (but not when the opening parenthesis is followed by @litchar{?}). Matches for the sub-expressions are provided in the order of the opening parentheses in @racket[pattern]. When sub-expressions occur in branches of an @@ -711,7 +711,7 @@ is replaced with the matching portion of @racket[input] before it is substituted into the match's place. If @racket[insert] contains @litchar{\}@nonterm{n} for some integer @nonterm{n}, then it is replaced with the @nonterm{n}th matching sub-expression from -@racket[input]. A @litchar{&} and @litchar{\0} are synonymous. If +@racket[input]. A @litchar{&} and @litchar{\0} are aliases. If the @nonterm{n}th sub-expression was not used in the match, or if @nonterm{n} is greater than the number of sub-expressions in @racket[pattern], then @litchar{\}@nonterm{n} is replaced with the diff --git a/collects/scribblings/reference/sandbox.scrbl b/collects/scribblings/reference/sandbox.scrbl index dfdee6878f..c22aec5b11 100644 --- a/collects/scribblings/reference/sandbox.scrbl +++ b/collects/scribblings/reference/sandbox.scrbl @@ -285,7 +285,7 @@ sandboxed environment --- one that is safe to make publicly available. Further customizations might be needed in case more privileges are needed, or if you want tighter restrictions. Another useful approach for customizing an evaluator is to begin with a relatively -unrestricted configuration and add the desired restrictions. This is +unrestricted configuration and add the desired restrictions. This approach is made possible by the @racket[call-with-trusted-sandbox-configuration] function. diff --git a/collects/scribblings/reference/semaphores.scrbl b/collects/scribblings/reference/semaphores.scrbl index 45cf3660f5..a2da326681 100644 --- a/collects/scribblings/reference/semaphores.scrbl +++ b/collects/scribblings/reference/semaphores.scrbl @@ -19,6 +19,12 @@ thread is eventually unblocked. In addition to its use with semaphore-specific procedures, semaphores can be used as events; see @secref["sync"]. +@defproc[(semaphore? [v any/c]) boolean?]{ + +Returns @scheme[#t] if @scheme[v] is a @tech{semaphore}, +@scheme[#f] otherwise.} + + @defproc[(make-semaphore [init exact-nonnegative-integer? 0]) semaphore?]{ Creates and returns a new semaphore with the counter initially set to @@ -26,12 +32,6 @@ Creates and returns a new semaphore with the counter initially set to internal counter value, the @exnraise[exn:fail].} -@defproc[(semaphore? [v any/c]) boolean?]{ - -Returns @scheme[#t] if @scheme[v] is a semaphore created by -@scheme[make-semaphore], @scheme[#f] otherwise.} - - @defproc[(semaphore-post [sema semaphore?]) void?]{Increments the semaphore's internal counter and returns @|void-const|. If the semaphore's internal counter has already reached its maximum value, diff --git a/collects/scribblings/reference/sequences.scrbl b/collects/scribblings/reference/sequences.scrbl index 634baced08..16eeab0232 100644 --- a/collects/scribblings/reference/sequences.scrbl +++ b/collects/scribblings/reference/sequences.scrbl @@ -518,7 +518,7 @@ in the sequence. @defform[(infinite-generator body ...)]{ Creates a function similar to @scheme[generator] but when the last - @scheme[body] is evaluated, the function will re-evaluates all the bodies + @scheme[body] is evaluated, the function will re-evaluate all of the bodies in a loop. @examples[#:eval generator-eval diff --git a/collects/scribblings/reference/serialization.scrbl b/collects/scribblings/reference/serialization.scrbl index 74dfee320b..fb6d5ceaab 100644 --- a/collects/scribblings/reference/serialization.scrbl +++ b/collects/scribblings/reference/serialization.scrbl @@ -145,7 +145,7 @@ elements: @item{a pair whose @scheme[car] is @scheme['v] and whose @scheme[cdr] is a non-negative exact integer @scheme[_s] - for a vector of length @scheme[_s]; or} + for a vector of length @scheme[_s];} @item{a list whose first element is @scheme['h] and whose remaining elements are symbols that determine the @@ -208,7 +208,7 @@ elements: @item{a pair whose @scheme[car] is @scheme['f]; it represents an instance of a @tech{prefab} structure - type. The @scheme[cadr] of the pair is @tech{prefab} + type. The @scheme[cadr] of the pair is a @tech{prefab} structure type key, and the @scheme[cddr] is a list of serials representing the field values.} @@ -216,7 +216,7 @@ elements: representing @|void-const|.} @item{a pair whose @scheme[car] is @scheme['su] and whose - @scheme[cdr] is a character string; it represents a + @scheme[cdr] is a character string; it represents an @tech{unreadable symbol}.} @item{a pair whose @scheme[car] is @scheme['u] and whose @@ -241,7 +241,7 @@ elements: @item{a pair whose @scheme[car] is @scheme['c!] and whose @scheme[cdr] is a pair of serials; it represents a - pair (but formerly presented a mutable pair), and + pair (but formerly represented a mutable pair), and does not appear in output generated by @scheme[serialize].} @@ -285,7 +285,7 @@ elements: @scheme[arity-at-least] structure.} @item{a pair whose @scheme[car] is @scheme['mpi] and whose - @scheme[cdr] is a pair; it represents an + @scheme[cdr] is a pair; it represents a @tech{module path index} that joins the paired values.} @@ -379,7 +379,7 @@ The @scheme[-v0] suffix on the deserialization enables future versioning on the structure type through @scheme[serializable-struct/version]. -When a supertype is supplied in @scheme[maybe-super] is supplied, +When a supertype is supplied as @scheme[maybe-super], compile-time information bound to the supertype identifier must include all of the supertype's field accessors. If any field mutator is missing, the structure type will be treated as immutable for the @@ -402,7 +402,7 @@ default constructor name of @racket[define-struct].} @; ---------------------------------------------------------------------- -@defform/subs[(serializable-struct/versions id-maybe-super vers (field ...) +@defform/subs[(serializable-struct/versions id maybe-super vers (field ...) (other-version-clause ...) struct-option ...) ([other-version-clause (other-vers make-proc-expr @@ -460,7 +460,7 @@ instance of @scheme[id] and copies its field values into @scheme[x]. (other-version-clause ...) struct-option ...)]{ Like @racket[serializable-struct/versions], but with the supertype syntax and -default constructor name of @racket[define-struct].} +default constructor name of @racket[define-struct]. } @; ---------------------------------------------------------------------- @@ -476,7 +476,7 @@ particular structure because the structure has a variable or module-exported variable that is bound to deserialization information. -The @scheme[make] procedure should accept as many argument as the +The @scheme[make] procedure should accept as many arguments as the structure's serializer put into a vector; normally, this is the number of fields in the structure. It should return an instance of the structure. diff --git a/collects/scribblings/reference/startup.scrbl b/collects/scribblings/reference/startup.scrbl index 6000b8dae9..ca0ec01da0 100644 --- a/collects/scribblings/reference/startup.scrbl +++ b/collects/scribblings/reference/startup.scrbl @@ -42,7 +42,7 @@ The core Racket run-time system is available in two main variants: @section[#:tag "init-actions"]{Initialization} -On startup, the top-level environment contains no bindings---not even +On start-up, the top-level environment contains no bindings---not even @racket[#%app] for function application. Primitive modules with names that start with @racketidfont{#%} are defined, but they are not meant for direct use, and the set of such modules can change. For example, diff --git a/collects/scribblings/reference/string-input.scrbl b/collects/scribblings/reference/string-input.scrbl index 09e3915f91..2a2f5a4f5f 100644 --- a/collects/scribblings/reference/string-input.scrbl +++ b/collects/scribblings/reference/string-input.scrbl @@ -118,7 +118,7 @@ modified. If no bytes are available before an end-of-file, then @scheme[eof] is returned. Otherwise, the return value is the number of characters read. If @math{m} characters are read and @math{m<@scheme[end-pos]-@scheme[start-pos]}, then @scheme[str] is -not modified at indices @math{@scheme[start-pos]+m} though +not modified at indices @math{@scheme[start-pos]+m} through @scheme[end-pos].} @defproc[(read-bytes! [bstr bytes?] @@ -135,8 +135,8 @@ string, and returns the number of bytes read.} [end-pos exact-nonnegative-integer? (bytes-length bstr)]) (or/c exact-positive-integer? eof-object? procedure?)]{ -Like @scheme[read-bytes!], but it returns without blocking after -reading immediately-available bytes, and it may return a procedure for +Like @scheme[read-bytes!], but returns without blocking after having +read the immediately available bytes, and it may return a procedure for a ``special'' result. The @scheme[read-bytes-avail!] procedure blocks only if no bytes (or specials) are yet available. Also unlike @scheme[read-bytes!], @scheme[read-bytes-avail!] never drops bytes; if @@ -284,10 +284,10 @@ with @scheme[skip-bytes-amt] and @scheme[progress] arguments like @defproc[(read-char-or-special [in input-port? (current-input-port)]) (or/c character? eof-object? any/c)]{ -Like @scheme[read-char], but that if the input port returns a non-byte +Like @scheme[read-char], but if the input port returns a non-byte value (through a value-generating procedure in a custom port; see @secref["customport"] and @secref["special-comments"] for -details), the non-byte value is returned.} +details), then the non-byte value is returned.} @defproc[(read-byte-or-special [in input-port? (current-input-port)]) (or/c byte? eof-object? any/c)]{ @@ -299,7 +299,7 @@ instead of a character.} [skip-bytes-amt exact-nonnegative-integer? 0]) (or/c character? eof-object?)]{ -Like @scheme[read-char], but peeks instead of reading, and skipping +Like @scheme[read-char], but peeks instead of reading, and skips @scheme[skip-bytes-amt] bytes (not characters) at the start of the port.} @@ -315,7 +315,7 @@ character.} (or/c character? eof-object? any/c)]{ Like @scheme[peek-char], but if the input port returns a non-byte -value after @scheme[skip-bytes-amt] byte positions, it is returned.} +value after @scheme[skip-bytes-amt] byte positions, then it is returned.} @defproc[(peek-byte-or-special [in input-port? (current-input-port)] [skip-bytes-amt exact-nonnegative-integer? 0] @@ -332,7 +332,7 @@ like @scheme[peek-bytes-avail!].} Returns an event that becomes ready after any subsequent read from @scheme[in], or after @scheme[in] is closed. After the event becomes ready, it remains ready. If progress events are unavailable for -@scheme[in] (as reported by @scheme[port-provides-progress-evts?]) the +@scheme[in] (as reported by @scheme[port-provides-progress-evts?]), then the @exnraise[exn:fail:contract].} @defproc[(port-provides-progress-evts? [in input-port?]) boolean]{ @@ -352,7 +352,7 @@ Attempts to commit as read the first @scheme[amt] previously peeked bytes, non-byte specials, and @scheme[eof]s from @scheme[in], or the first @scheme[eof] or special value peeked from @scheme[in]. (Only mid-stream @scheme[eof]s can be -committed. A @scheme[eof] when the port is exhausted does not +committed. An @scheme[eof] when the port is exhausted does not correspond to data in the stream.) The read commits only if @scheme[progress] does not become ready first @@ -364,7 +364,7 @@ channel, semaphore, semaphore-peek event, always event, or never event. Suspending the thread that calls @scheme[port-commit-peeked] may or may not prevent the commit from proceeding. -The result from @scheme[port-commit-peeked] is @scheme[#t] if data is +The result from @scheme[port-commit-peeked] is @scheme[#t] if data has been committed, and @scheme[#f] otherwise. If no data has been peeked from @scheme[in] and @scheme[progress] is diff --git a/collects/scribblings/reference/string-output.scrbl b/collects/scribblings/reference/string-output.scrbl index 07cd31da58..bc881af24a 100644 --- a/collects/scribblings/reference/string-output.scrbl +++ b/collects/scribblings/reference/string-output.scrbl @@ -54,9 +54,9 @@ as many bytes as it can immediately flush. It blocks only if no bytes can be flushed immediately. The result is the number of bytes written and flushed to @racket[out]; if @racket[start-pos] is the same as @racket[end-pos], then the result can be @racket[0] (indicating a -successful flush of any buffered data), otherwise the result is at -least @racket[1] but possibly less than @racket[(- end-pos -start-pos)]. +successful flush of any buffered data), otherwise the result is between +@racket[1] and @racket[(- end-pos +start-pos)], inclusive. The @racket[write-bytes-avail] procedure never drops bytes; if @racket[write-bytes-avail] successfully writes some bytes and then diff --git a/collects/scribblings/reference/string-ports.scrbl b/collects/scribblings/reference/string-ports.scrbl index 8584619ac0..9a050f5532 100644 --- a/collects/scribblings/reference/string-ports.scrbl +++ b/collects/scribblings/reference/string-ports.scrbl @@ -36,8 +36,8 @@ same as @scheme[open-output-bytes].} bytes?]{ Returns the bytes accumulated in @scheme[out] so far in a -freshly-allocated byte string (including any bytes written after the -port's current position, if any). the @scheme[out] port must be a +freshly allocated byte string (including any bytes written after the +port's current position, if any). The @scheme[out] port must be a string output port produced by @scheme[open-output-bytes] (or @scheme[open-output-string]) or a structure whose @scheme[prop:output-port] property refers to such an output port diff --git a/collects/scribblings/reference/strings.scrbl b/collects/scribblings/reference/strings.scrbl index 68fe099fb2..532dca5053 100644 --- a/collects/scribblings/reference/strings.scrbl +++ b/collects/scribblings/reference/strings.scrbl @@ -145,7 +145,7 @@ contains the concatenated characters of the given @scheme[str]s. If no @defproc[(string->list [str string?]) (listof char?)]{ Returns a new list of characters corresponding to the content of @scheme[str]. That is, the length of the list is @scheme[(string-length str)], and the - sequence of characters of @scheme[str] is the same sequence in the + sequence of characters in @scheme[str] is the same sequence in the result list. @mz-examples[(string->list "Apple")]} @@ -154,7 +154,7 @@ contains the concatenated characters of the given @scheme[str]s. If no @defproc[(list->string [lst (listof char?)]) string?]{ Returns a new mutable string whose content is the list of characters in @scheme[lst]. That is, the length of the string is @scheme[(length lst)], and - the sequence of characters in @scheme[lst] is in the same sequence in + the sequence of characters in @scheme[lst] is the same sequence in the result string. @mz-examples[(list->string (list #\A #\p #\p #\l #\e))]} diff --git a/collects/scribblings/reference/stx-trans.scrbl b/collects/scribblings/reference/stx-trans.scrbl index bb030faf79..5b19bd5467 100644 --- a/collects/scribblings/reference/stx-trans.scrbl +++ b/collects/scribblings/reference/stx-trans.scrbl @@ -178,7 +178,7 @@ value and @scheme[cons] it onto the current result of @scheme[syntax-local-context] if it is a list. When an identifier in @scheme[stop-ids] is encountered by the expander -in a subexpression, expansions stops for the subexpression. If +in a sub-expression, expansions stops for the sub-expression. If @scheme[stop-ids] is a non-empty list, then @scheme[begin], @scheme[quote], @scheme[set!], @scheme[lambda], @scheme[case-lambda], @scheme[let-values], @scheme[letrec-values], @@ -347,7 +347,7 @@ Binds each identifier in @scheme[id-list] within the @scheme[expr] when the identifiers correspond to @scheme[define-values] bindings, and supply a compile-time expression when the identifiers correspond to @scheme[define-syntaxes] bindings; -the latter case, the number of values produced by the expression should +in the latter case, the number of values produced by the expression should match the number of identifiers, otherwise the @exnraise[exn:fail:contract:arity]. diff --git a/collects/scribblings/reference/syntax-model.scrbl b/collects/scribblings/reference/syntax-model.scrbl index 58ae6c92b3..25c697c294 100644 --- a/collects/scribblings/reference/syntax-model.scrbl +++ b/collects/scribblings/reference/syntax-model.scrbl @@ -573,9 +573,9 @@ way that unexported and protected @tech{module bindings} are used. See @secref["stxcerts"] for more information on @tech{syntax certificates}. -The expander's handling of @racket[letrec-values+syntaxes] is similar +The expander's handling of @racket[letrec-syntaxes+values] is similar to its handling of @racket[define-syntaxes]. A -@racket[letrec-values+syntaxes] might be expanded in an arbitrary phase +@racket[letrec-syntaxes+values] can be expanded in an arbitrary phase level @math{n} (not just 0), in which case the expression for the @tech{transformer binding} is expanded at @tech{phase level} @math{n+1}. @@ -633,7 +633,7 @@ recursively expands only until the form becomes one of the following: @racket[define-values] form before expansion continues. When a @racket[define-syntaxes] form is discovered, the right-hand side is expanded and evaluated (as for a - @racket[letrec-values+syntaxes] form), and a transformer + @racket[letrec-syntaxes+values] form), and a transformer binding is installed for the body sequence before expansion continues.} diff --git a/collects/scribblings/reference/syntax.scrbl b/collects/scribblings/reference/syntax.scrbl index 4c6d253ebf..98f7c85e76 100644 --- a/collects/scribblings/reference/syntax.scrbl +++ b/collects/scribblings/reference/syntax.scrbl @@ -1041,10 +1041,11 @@ context of the @racket[phaseless-spec] form.} The following forms support more complex selection and manipulation of sets of imported identifiers. -@defform[(matching-identifiers-in regexp require-spec)]{ Like - @racket[require-spec], but including only imports whose names match - @racket[regexp]. The @racket[regexp] must be a literal regular - expression (see @secref["regexp"]). +@defform[(matching-identifiers-in regexp require-spec)]{ + +Like @racket[require-spec], but including only imports whose names + match @racket[regexp]. The @racket[regexp] must be a literal regular + expression (see @secref["regexp"]). @defexamples[#:eval (syntax-eval) (module zoo racket/base @@ -1064,8 +1065,9 @@ blowfish monkey ]} -@defform[(subtract-in require-spec subtracted-spec ...)]{ Like - @racket[require-spec], but omitting those imports that would be +@defform[(subtract-in require-spec subtracted-spec ...)]{ + +Like @racket[require-spec], but omitting those imports that would be imported by one of the @racket[subtracted-spec]s. @defexamples[#:eval (syntax-eval) @@ -1119,17 +1121,18 @@ directory, etc., all the way to the root directory. The discovered path relative to the enclosing source becomes part of the expanded form. -This form is useful in setting up a ``project environment''. For -example, you can write a @filepath{config.ss} file in the root -directory of your project with: +This form is useful in setting up a ``project environment.'' For +example, using the following @filepath{config.rkt} file in the root +directory of your project: @racketmod[ racket/base - (require racket/require-syntax (for-syntax "utils/in-here.ss")) + (require racket/require-syntax + (for-syntax "utils/in-here.rkt")) ;; require form for my utilities (provide utils-in) (define-require-syntax utils-in in-here-transformer) ] -and in @filepath{utils/in-here.ss} in the root: +and using @filepath{utils/in-here.rkt} under the same root directory: @racketmod[ racket/base (require racket/runtime-path) @@ -1139,22 +1142,26 @@ and in @filepath{utils/in-here.ss} in the root: (syntax-case stx () [(_ sym) (identifier? #'sym) - (let ([path (build-path here (format "~a.ss" (syntax-e #'sym)))]) + (let ([path (build-path here (format "~a.rkt" (syntax-e #'sym)))]) (datum->syntax stx `(file ,(path->string path)) stx))])) ] -Finally, you can use it via @racket[path-up]: +then @racket[path-up] works for any other module under the project + directory to find @filepath{config.rkt}: @racketblock[ - (require racket/require (path-up "config.ss") (utils-in foo))] -Note that the order of requires in this example is important, as each of + (require racket/require + (path-up "config.rkt") + (utils-in foo))] +Note that the order of requires in the example is important, as each of the first two bind the identifier used in the following. An alternative in this scenario is to use @racket[path-up] directly to -get to the utility module: +find the utility module: @racketblock[ - (require racket/require (path-up "utils/foo.ss"))] -but then you need to be careful with subdirectories that are called -@filepath{utils}, which will override the one in the project's root. -In other words, the previous method requires a single unique name.} + (require racket/require + (path-up "utils/foo.rkt"))] +but then sub-directories that are called +@filepath{utils} override the one in the project's root. +In other words, the previous method requires only a single unique name.} @; -------------------- diff --git a/collects/scribblings/reference/thread-cells.scrbl b/collects/scribblings/reference/thread-cells.scrbl index 95bef0344c..343f5d6244 100644 --- a/collects/scribblings/reference/thread-cells.scrbl +++ b/collects/scribblings/reference/thread-cells.scrbl @@ -26,6 +26,12 @@ values can be imperatively installed into the current thread through another call to @scheme[current-preserved-thread-cell-values]. The capturing and restoring threads can be different. + +@defproc[(thread-cell? [v any/c]) boolean?]{ +Returns @scheme[#t] if @scheme[v] is a @tech{thread cell}, +@scheme[#f] otherwise.} + + @defproc[(make-thread-cell [v any/c] [preserved? any/c #f]) thread-cell?]{ Creates and returns a new thread cell. Initially, @scheme[v] is the @@ -35,11 +41,6 @@ thread's value for the cell, otherwise the cell's value is initially @scheme[v] in all future threads.} -@defproc[(thread-cell? [v any/c]) boolean?]{ -Returns @scheme[#t] if @scheme[v] is a thread cell created by -@scheme[make-thread-cell], @scheme[#f] otherwise.} - - @defproc[(thread-cell-ref [cell thread-cell?]) any]{Returns the current value of @scheme[cell] for the current thread.} diff --git a/collects/scribblings/reference/time.scrbl b/collects/scribblings/reference/time.scrbl index 3aa136b382..a1894a0fc8 100644 --- a/collects/scribblings/reference/time.scrbl +++ b/collects/scribblings/reference/time.scrbl @@ -72,7 +72,7 @@ See also the @racketmodname[racket/date] library.} Returns the current ``time'' in @tech{fixnum} milliseconds (possibly negative). This time is based on a platform-specific starting date or -on the machine's startup time. Since the result is a @tech{fixnum}, +on the machine's start-up time. Since the result is a @tech{fixnum}, the value increases only over a limited (though reasonably long) time.} diff --git a/collects/scribblings/reference/units.scrbl b/collects/scribblings/reference/units.scrbl index a7d2202dfa..63b2e4e299 100644 --- a/collects/scribblings/reference/units.scrbl +++ b/collects/scribblings/reference/units.scrbl @@ -117,7 +117,7 @@ As suggested by the grammar, these adjustments to a signature can be nested arbitrarily. A unit's declared imports are matched with actual supplied imports by -signature. That is, the order in which imports are suppplied to a unit +signature. That is, the order in which imports are supplied to a unit when linking is irrelevant; all that matters is the signature implemented by each supplied import. One actual import must be provided for each declared import. Similarly, when a unit implements diff --git a/collects/scribblings/reference/write.scrbl b/collects/scribblings/reference/write.scrbl index 8fb34064c0..ef41039dd0 100644 --- a/collects/scribblings/reference/write.scrbl +++ b/collects/scribblings/reference/write.scrbl @@ -168,14 +168,14 @@ Formats to a string. The result is the same as @defboolparam[print-pair-curly-braces on?]{ -A parameter that control pair printing. If the value is true, then +A parameter that controls pair printing. If the value is true, then pairs print using @litchar["{"] and @litchar["}"] instead of @litchar{(} and @litchar{)}. The default is @racket[#f].} @defboolparam[print-mpair-curly-braces on?]{ -A parameter that control pair printing. If the value is true, then +A parameter that controls pair printing. If the value is true, then mutable pairs print using @litchar["{"] and @litchar["}"] instead of @litchar{(} and @litchar{)}. The default is @racket[#t].} @@ -225,7 +225,7 @@ A parameter that controls printing hash tables; defaults to A parameter that controls printing of booleans. When the parameter's value is true, @racket[#t] and @racket[#f] print as @litchar{#true} and @litchar{#false}, otherwise they print as @litchar{#t} -and @litchar{#f}.} +and @litchar{#f}. The default is @racket[#f].} @defboolparam[print-reader-abbreviations on?]{ @@ -245,7 +245,7 @@ to @racket[write] or @racket[display]); defaults to @racket[#t]. See @defboolparam[print-honu on?]{ A parameter that controls printing values in an alternate syntax. See -@|HonuManual| for more information.} +@|HonuManual| for more information. The default is @racket[#f].} @defparam[print-syntax-width width (or/c +inf.0 0 (and/c exact-integer? (>/c 3)))]{ @@ -266,7 +266,7 @@ names. When not @racket[#f], paths that syntactically extend the parameter's value are converted to relative paths; when the resulting compiled code is read, relative paths are converted back to complete paths using the @racket[current-load-relative-directory] parameter (if -it is not @racket[#f], otherwise the path is left relative).} +it is not @racket[#f]; otherwise, the path is left relative).} @@ -287,7 +287,7 @@ it is not @racket[#f], otherwise the path is left relative).} Gets or sets the @deftech{port write handler}, @deftech{port display handler}, or @deftech{port print handler} for @racket[out]. This -handler is call to output to the port when @racket[write], +handler is called to output to the port when @racket[write], @racket[display], or @racket[print] (respectively) is applied to the port. Each handler must accept two arguments: the value to be printed and the destination port. The handler's return value is ignored. diff --git a/collects/scribblings/scribble/style.scrbl b/collects/scribblings/scribble/style.scrbl index 90417f8f1f..29c554389d 100644 --- a/collects/scribblings/scribble/style.scrbl +++ b/collects/scribblings/scribble/style.scrbl @@ -40,7 +40,7 @@ Use the word ``list'' only when you mean a run-time value consisting of the empty list and cons cells; use the word ``sequence'' in other cases, if you must use any word. For example, do not write that @racket[begin] has a ``list of sub-forms;'' instead, it has a -``sequence of subforms.'' Similarly, do not refer to a ``list of +``sequence of sub-forms.'' Similarly, do not refer to a ``list of arguments'' in a function call; just write ``arguments'' if possible, or write ``sequence of argument expressions.'' (Unfortunately, ``@tech[#:doc '(lib @@ -56,6 +56,8 @@ except that ...,'' instead of abstracting the source and instantiating it multiple times; often, a prose abstraction is clearer to the reader than a hidden abstraction in the document implementation. +Hyphenate the words ``sub-form'' and ``sub-expression.'' + @section{Typesetting Code} Use @racketidfont{id} or a name that ends @racketidfont{-id} in @@ -149,6 +151,10 @@ Do not start a sentence with a Racket variable name, since it is normally lowercase. For example, use ``The @racket[_thing] argument is...'' instead of ``@racket[_thing] is...'' +Use @racket[etc] for ``@|etc|'' when it does not end a sentence, and +include a comma after ``@|etc|'' unless it ends a sentence of is +followed by other punctuation (such as a parenthesis). + @section{Section Titles} Capitalize all words except articles (``the,'' ``a,'' etc.),