From a1eaecb337f2d4e55c7f8638b70226c76554f204 Mon Sep 17 00:00:00 2001 From: Matthew Flatt Date: Mon, 15 Aug 2011 18:54:32 -0600 Subject: [PATCH] add an `#:escape' clause to all `schemeblock'-like forms --- collects/scribble/eval.rkt | 118 ++++++++++---------- collects/scribble/private/manual-scheme.rkt | 8 +- collects/scribble/racket.rkt | 102 +++++++++-------- collects/scribblings/scribble/eval.scrbl | 79 ++++++------- collects/scribblings/scribble/manual.scrbl | 86 +++++++------- collects/scribblings/scribble/scheme.scrbl | 11 +- 6 files changed, 211 insertions(+), 193 deletions(-) diff --git a/collects/scribble/eval.rkt b/collects/scribble/eval.rkt index 645ce3a97d..200ed21b6d 100644 --- a/collects/scribble/eval.rkt +++ b/collects/scribble/eval.rkt @@ -386,45 +386,48 @@ (define-syntax racketinput* (syntax-rules (eval:alts code:comment) - [(_ (code:comment . rest)) (racketblock0 (code:comment . rest))] - [(_ (eval:alts a b)) (racketinput* a)] - [(_ e) (racketinput0 e)])) + [(_ #:escape id (code:comment . rest)) (racketblock0 #:escape id (code:comment . rest))] + [(_ #:escape id (eval:alts a b)) (racketinput* #:escape id a)] + [(_ #:escape id e) (racketinput0 #:escape id e)])) (define-code racketblock0+line (to-paragraph/prefix "" "" (list " "))) (define-syntax (racketdefinput* stx) (syntax-case stx (define define-values define-struct) - [(_ (define . rest)) + [(_ #:escape id (define . rest)) (syntax-case stx () - [(_ e) #'(racketblock0+line e)])] - [(_ (define-values . rest)) + [(_ #:escape _ e) #'(racketblock0+line #:escape id e)])] + [(_ #:escape id (define-values . rest)) (syntax-case stx () - [(_ e) #'(racketblock0+line e)])] - [(_ (define-struct . rest)) + [(_ #:escape _ e) #'(racketblock0+line #:escape id e)])] + [(_ #:escape id (define-struct . rest)) (syntax-case stx () - [(_ e) #'(racketblock0+line e)])] - [(_ (code:line (define . rest) . rest2)) + [(_ #:escape _ e) #'(racketblock0+line #:escape id e)])] + [(_ #:escape id (code:line (define . rest) . rest2)) (syntax-case stx () - [(_ e) #'(racketblock0+line e)])] - [(_ e) #'(racketinput* e)])) + [(_ #:escape _ e) #'(racketblock0+line #:escape id e)])] + [(_ #:escape id e) #'(racketinput* #:escape id e)])) (define (do-titled-interaction who inset? ev t shows evals) (interleave inset? t shows (map (do-eval ev who) evals))) (define-syntax titled-interaction (syntax-rules () - [(_ who inset? #:eval ev t racketinput* e ...) + [(_ who inset? t racketinput* #:eval ev #:escape unsyntax-id e ...) (do-titled-interaction - 'who inset? ev t (list (racketinput* e) ...) (list (quote-expr e) ...))] + 'who inset? ev t (list (racketinput* #:escape unsyntax-id e) ...) (list (quote-expr e) ...))] + [(_ who inset? t racketinput* #:eval ev e ...) + (titled-interaction + who inset? t racketinput* #:eval ev #:escape unsyntax e ...)] + [(_ who inset? t racketinput* #:escape unsyntax-id e ...) + (titled-interaction + who inset? t racketinput* #:eval (make-base-eval) #:escape unsyntax-id e ...)] [(_ who inset? t racketinput* e ...) (titled-interaction - who inset? #:eval (make-base-eval) t racketinput* e ...)])) + who inset? t racketinput* #:eval (make-base-eval) e ...)])) (define-syntax (-interaction stx) (syntax-case stx () - [(_ who #:eval ev e ...) - (syntax/loc stx - (titled-interaction who #f #:eval ev #f racketinput* e ...))] [(_ who e ...) (syntax/loc stx (titled-interaction who #f #f racketinput* e ...))])) @@ -437,57 +440,70 @@ (syntax-case stx () [(H e ...) (syntax/loc stx (-interaction H e ...))])) -(define-syntax racketblock+eval +(define-syntax racketblockX+eval (syntax-rules () - [(_ #:eval ev e ...) + [(_ racketblock #:eval ev #:escape unsyntax-id e ...) (let ([eva ev]) (#%expression (begin (interaction-eval #:eval eva e) ... - (racketblock e ...))))] + (racketblock #:escape unsyntax-id e ...))))] + [(_ racketblock #:eval ev e ...) + (racketblockX+eval racketblock #:eval ev #:escape unsyntax e ...)] + [(_ racketblock #:escape unsyntax-id e ...) + (racketblockX+eval racketblock #:eval (make-base-eval) #:escape unsyntax-id e ...)] + [(_ racketblock e ...) + (racketblockX+eval racketblock #:eval (make-base-eval) #:escape unsyntax e ...)])) + +(define-syntax racketblock+eval + (syntax-rules () [(_ e ...) - (racketblock+eval #:eval (make-base-eval) e ...)])) + (racketblockX+eval racketblock e ...)])) (define-syntax racketblock0+eval (syntax-rules () - [(_ #:eval ev e ...) - (let ([eva ev]) - (#%expression (begin (interaction-eval #:eval eva e) ... - (racketblock0 e ...))))] [(_ e ...) - (racketblock0+eval #:eval (make-base-eval) e ...)])) + (racketblockX+eval racketblock0 e ...)])) (define-syntax racketmod+eval (syntax-rules () - [(_ #:eval ev name e ...) + [(_ #:eval ev #:escape unsyntax-id name e ...) (let ([eva ev]) (#%expression (begin (interaction-eval #:eval eva e) ... - (racketmod name e ...))))] + (racketmod #:escape unsyntax-id name e ...))))] + [(_ #:eval ev name e ...) + (racketmod+eval #:eval ev #:escape unsyntax name e ...)] + [(_ #:escape unsyntax-id name e ...) + (racketmod+eval #:eval (make-base-eval) #:escape unsyntax-id name e ...)] [(_ name e ...) - (racketmod+eval #:eval (make-base-eval) name e ...)])) - -(define-syntax (def+int stx) - (syntax-case stx () - [(H #:eval ev def e ...) - (syntax/loc stx - (let ([eva ev]) - (column (list (racketblock0+eval #:eval eva def) - blank-line - (-interaction H #:eval eva e ...)))))] - [(_ def e ...) - (syntax/loc stx (def+int #:eval (make-base-eval) def e ...))])) + (racketmod+eval #:eval (make-base-eval) #:escape unsyntax name e ...)])) (define-syntax (defs+int stx) (syntax-case stx () - [(H #:eval ev [def ...] e ...) + [(H #:eval ev #:escape unsyntax-id [def ...] e ...) (syntax/loc stx (let ([eva ev]) - (column (list (racketblock0+eval #:eval eva def ...) + (column (list (racketblock0+eval #:eval eva #:escape unsyntax-id def ...) blank-line - (-interaction H #:eval eva e ...)))))] + (-interaction H #:eval eva #:escape unsyntax-id e ...)))))] + [(H #:eval ev [def ...] e ...) + (syntax/loc stx (defs+int #:eval ev #:escape unsyntax [def ...] e ...))] + [(_ #:escape unsyntax-id [def ...] e ...) + (syntax/loc stx (defs+int #:eval (make-base-eval) #:escape unsyntax-id [def ...] e ...))] [(_ [def ...] e ...) (syntax/loc stx (defs+int #:eval (make-base-eval) [def ...] e ...))])) +(define-syntax def+int + (syntax-rules () + [(H #:eval ev #:escape unsyntax-id def e ...) + (defs+int #:eval ev #:escape unsyntax-id [def] e ...)] + [(H #:eval ev def e ...) + (defs+int #:eval ev [def] e ...)] + [(H #:escape unsyntax-id def e ...) + (defs+int #:escape unsyntax-id [def] e ...)] + [(H def e ...) + (defs+int [def] e ...)])) + (define example-title (make-paragraph (list "Example:"))) (define examples-title @@ -500,37 +516,23 @@ (define-syntax (examples stx) (syntax-case stx () - [(H #:eval ev e ...) - (syntax/loc stx - (titled-interaction - H #t #:eval ev (pick-example-title e ...) racketinput* e ...))] [(H e ...) (syntax/loc stx (titled-interaction H #t (pick-example-title e ...) racketinput* e ...))])) (define-syntax (examples* stx) (syntax-case stx () - [(H #:eval ev example-title e ...) - (syntax/loc stx - (titled-interaction H #t #:eval ev example-title racketinput* e ...))] [(H example-title e ...) (syntax/loc stx (titled-interaction H #t example-title racketinput* e ...))])) (define-syntax (defexamples stx) (syntax-case stx () - [(H #:eval ev e ...) - (syntax/loc stx - (titled-interaction - H #t #:eval ev (pick-example-title e ...) racketdefinput* e ...))] [(H e ...) (syntax/loc stx (titled-interaction H #t (pick-example-title e ...) racketdefinput* e ...))])) (define-syntax (defexamples* stx) (syntax-case stx () - [(H #:eval ev example-title e ...) - (syntax/loc stx - (titled-interaction H #t #:eval ev example-title racketdefinput* e ...))] [(H example-title e ...) (syntax/loc stx (titled-interaction H #t example-title racketdefinput* e ...))])) diff --git a/collects/scribble/private/manual-scheme.rkt b/collects/scribble/private/manual-scheme.rkt index dc65f12974..fed6472a1c 100644 --- a/collects/scribble/private/manual-scheme.rkt +++ b/collects/scribble/private/manual-scheme.rkt @@ -89,7 +89,7 @@ (define-syntax (racketmod0 stx) (syntax-case stx () - [(_ #:file filename lang rest ...) + [(_ #:file filename #:escape unsyntax-id lang rest ...) (with-syntax ([modtag (datum->syntax #'here `(unsyntax (make-element @@ -106,8 +106,10 @@ (quasisyntax/loc stx (filebox filename - #,(syntax/loc stx (racketblock0 modtag rest ...)))) - (syntax/loc stx (racketblock0 modtag rest ...))))] + #,(syntax/loc stx (racketblock0 #:escape unsyntax-id modtag rest ...)))) + (syntax/loc stx (racketblock0 #:escape unsyntax-id modtag rest ...))))] + [(_ #:file filename lang rest ...) + (syntax/loc stx (racketmod0 #:file #f #:escape unsyntax lang rest ...))] [(_ lang rest ...) (syntax/loc stx (racketmod0 #:file #f lang rest ...))])) diff --git a/collects/scribble/racket.rkt b/collects/scribble/racket.rkt index 195abc25e9..bcbabb18c6 100644 --- a/collects/scribble/racket.rkt +++ b/collects/scribble/racket.rkt @@ -914,56 +914,64 @@ ,(syntax-column v) ,(syntax-position v) ,(syntax-span v)))) - (define (stx->loc-s-expr v) - (let ([slv (and (identifier? v) - (syntax-local-value v (lambda () #f)))]) - (cond - [(variable-id? slv) - (wrap-loc v #f `(,#'make-var-id ',(variable-id-sym slv)))] - [(element-id-transformer? slv) - (wrap-loc v #f ((element-id-transformer-proc slv) v))] - [(syntax? v) - (let ([mk (wrap-loc - v - `(quote-syntax ,(datum->syntax v 'defcode)) - (syntax-case v (uncode) - [(uncode e) #'e] - [else (stx->loc-s-expr (syntax-e v))]))]) - (let ([prop (syntax-property v 'paren-shape)]) - (if prop - `(,#'stx-prop ,mk 'paren-shape ,prop) - mk)))] - [(null? v) 'null] - [(list? v) `(list . ,(map stx->loc-s-expr v))] - [(pair? v) `(cons ,(stx->loc-s-expr (car v)) - ,(stx->loc-s-expr (cdr v)))] - [(vector? v) `(vector ,@(map - stx->loc-s-expr - (vector->list v)))] - [(and (struct? v) (prefab-struct-key v)) - `(make-prefab-struct (quote ,(prefab-struct-key v)) - ,@(map - stx->loc-s-expr - (cdr (vector->list (struct->vector v)))))] - [(box? v) `(box ,(stx->loc-s-expr (unbox v)))] - [(hash? v) `(,(cond - [(hash-eq? v) 'make-immutable-hasheq] - [(hash-eqv? v) 'make-immutable-hasheqv] - [else 'make-immutable-hash]) - (list - ,@(hash-map - v - (lambda (k v) - `(cons (quote ,k) - ,(stx->loc-s-expr v))))))] - [else `(quote ,v)]))) - (define (cvt s) - (datum->syntax #'here (stx->loc-s-expr s) #f)) + (define (stx->loc-s-expr/esc v uncode-id) + (define (stx->loc-s-expr v) + (let ([slv (and (identifier? v) + (syntax-local-value v (lambda () #f)))]) + (cond + [(variable-id? slv) + (wrap-loc v #f `(,#'make-var-id ',(variable-id-sym slv)))] + [(element-id-transformer? slv) + (wrap-loc v #f ((element-id-transformer-proc slv) v))] + [(syntax? v) + (let ([mk (wrap-loc + v + `(quote-syntax ,(datum->syntax v 'defcode)) + (syntax-case v () + [(esc e) + (and (identifier? #'esc) + (free-identifier=? #'esc uncode-id)) + #'e] + [else (stx->loc-s-expr (syntax-e v))]))]) + (let ([prop (syntax-property v 'paren-shape)]) + (if prop + `(,#'stx-prop ,mk 'paren-shape ,prop) + mk)))] + [(null? v) 'null] + [(list? v) `(list . ,(map stx->loc-s-expr v))] + [(pair? v) `(cons ,(stx->loc-s-expr (car v)) + ,(stx->loc-s-expr (cdr v)))] + [(vector? v) `(vector ,@(map + stx->loc-s-expr + (vector->list v)))] + [(and (struct? v) (prefab-struct-key v)) + `(make-prefab-struct (quote ,(prefab-struct-key v)) + ,@(map + stx->loc-s-expr + (cdr (vector->list (struct->vector v)))))] + [(box? v) `(box ,(stx->loc-s-expr (unbox v)))] + [(hash? v) `(,(cond + [(hash-eq? v) 'make-immutable-hasheq] + [(hash-eqv? v) 'make-immutable-hasheqv] + [else 'make-immutable-hash]) + (list + ,@(hash-map + v + (lambda (k v) + `(cons (quote ,k) + ,(stx->loc-s-expr v))))))] + [else `(quote ,v)]))) + (stx->loc-s-expr v)) + (define (cvt s uncode-id) + (datum->syntax #'here (stx->loc-s-expr/esc s uncode-id) #f)) (if (eq? (syntax-local-context) 'expression) (syntax-case stx () - [(_ expr) #`(typeset-code #,(cvt #'expr))] + [(_ #:escape uncode-id expr) #`(typeset-code #,(cvt #'expr #'uncode-id))] + [(_ expr) #`(typeset-code #,(cvt #'expr #'uncode))] + [(_ #:escape uncode-id expr (... ...)) + #`(typeset-code #,(cvt #'(code:line expr (... ...)) #'uncode-id))] [(_ expr (... ...)) - #`(typeset-code #,(cvt #'(code:line expr (... ...))))]) + #`(typeset-code #,(cvt #'(code:line expr (... ...)) #'uncode))]) (quasisyntax/loc stx (#%expression #,stx)))))] [(_ code typeset-code uncode d->s) diff --git a/collects/scribblings/scribble/eval.scrbl b/collects/scribblings/scribble/eval.scrbl index a0ed01f50c..9615c8d321 100644 --- a/collects/scribblings/scribble/eval.scrbl +++ b/collects/scribblings/scribble/eval.scrbl @@ -8,8 +8,11 @@ utilities for evaluating code at document-build time and incorporating the results in the document, especially to show example uses of defined procedures and syntax.} -@defform*[[(interaction datum ...) - (interaction #:eval eval-expr datum ...)]]{ +@defform/subs[(interaction maybe-eval maybe-escape datum ...) + ([maybe-eval code:blank + (code:line #:eval eval-expr)] + [maybe-escape code:blank + (code:line #:escape escape-id)])]{ Like @racket[racketinput], except that the result for each input @racket[datum] is shown on the next line. The result is determined by @@ -19,28 +22,10 @@ evaluator produced by @racket[eval-expr], if provided. The @racket[eval-expr] must produce a sandbox evaluator via @racket[make-evaluator] or @racket[make-module-evaluator] with the @racket[sandbox-output] and @racket[sandbox-error-output] parameters -set to @racket['string]. If @racket[eval] is not provided, an +set to @racket['string]. If @racket[eval-expr] is not provided, an evaluator is created using @racket[make-base-eval]. See also @racket[make-eval-factory]. -As an example, -@codeblock|{ -#lang scribble/manual -@(require racket/sandbox - scribble/eval) -@(define my-evaluator - (parameterize ([sandbox-output 'string] - [sandbox-error-output 'string]) - (make-evaluator 'typed/racket/base))) -@interaction[#:eval my-evaluator - - (: my-sqr (Real -> Real)) - (define (my-sqr x) - (* x x)) - (my-sqr 42)] -}| -uses an evaluator whose language is @racketmodname[typed/racket/base]. - If the value of @racket[current-print] in the sandbox is changed from its default value, or if @racket[print-as-expression] in the sandbox is set to @racket[#f], then each evaluation result is formatted to a @@ -61,67 +46,77 @@ typeset, while @svar[eval-datum] is evaluated. If a @racket[datum] has the form @racket[(@#,indexed-racket[eval:check] #,(svar eval-datum) #,(svar expect-datum))], then both @svar[eval-datum] and @svar[check-datum] -are evaluated, and an error is raised if they are not @racket[equal?].} +are evaluated, and an error is raised if they are not @racket[equal?]. -@defform*[[(interaction0 datum ...) - (interaction0 #:eval eval-expr datum ...)]]{ +As an example, + +@codeblock|{ +#lang scribble/manual +@(require racket/sandbox + scribble/eval) +@(define my-evaluator + (parameterize ([sandbox-output 'string] + [sandbox-error-output 'string]) + (make-evaluator 'typed/racket/base))) +@interaction[#:eval my-evaluator + + (: my-sqr (Real -> Real)) + (define (my-sqr x) + (* x x)) + (my-sqr 42)] +}| + +uses an evaluator whose language is @racketmodname[typed/racket/base].} + +@defform[(interaction0 maybe-eval maybe-escape datum ...)]{ Like @racket[interaction], but without insetting the code via @racket[nested].} -@defform*[[(interaction-eval datum) - (interaction-eval #:eval eval-expr datum)]]{ +@defform[(interaction-eval maybe-eval maybe-escape datum)]{ Like @racket[interaction], evaluates the @racket[quote]d form of @racket[datum], but returns the empty string.} -@defform*[[(interaction-eval-show datum) - (interaction-eval-show #:eval eval-expr datum)]]{ +@defform[(interaction-eval-show maybe-eval maybe-escape datum)]{ Like @racket[interaction-eval], but produces an element representing the printed form of the evaluation result.} -@defform*[[(racketblock+eval datum ...) - (racketblock+eval #:eval eval-expr datum ...)]]{ +@defform[(racketblock+eval maybe-eval maybe-escape datum ...)]{ Combines @racket[racketblock] and @racket[interaction-eval].} -@defform*[[(racketblock0+eval datum ...) - (racketblock0+eval #:eval eval-expr datum ...)]]{ +@defform[(racketblock0+eval maybe-eval maybe-escape datum ...)]{ Combines @racket[racketblock0] and @racket[interaction-eval].} -@defform*[[(racketmod+eval name datum ...) - (racketmod+eval #:eval eval-expr name datum ...)]]{ +@defform[(racketmod+eval maybe-eval maybe-escape name datum ...)]{ Combines @racket[racketmod] and @racket[interaction-eval].} -@defform*[[(def+int defn-datum expr-datum ...) - (def+int #:eval eval-expr defn-datum expr-datum ...)]]{ +@defform[(def+int maybe-eval maybe-escape defn-datum expr-datum ...)]{ Like @racket[interaction], except the @racket[defn-datum] is typeset as for @racket[racketblock] (i.e., no prompt) and a line of space is inserted before the @racket[expr-datum]s.} -@defform*[[(defs+int (defn-datum ...) expr-datum ...) - (defs+int #:eval eval-expr (defn-datum ...) expr-datum ...)]]{ +@defform[(defs+int maybe-eval maybe-escape (defn-datum ...) expr-datum ...)]{ Like @racket[def+int], but for multiple leading definitions.} -@defform*[[(examples datum ...) - (examples #:eval eval-expr datum ...)]]{ +@defform[(examples maybe-eval maybe-escape datum ...)]{ Like @racket[interaction], but with an ``Examples:'' label prefixed.} -@defform*[[(defexamples datum ...) - (defexamples #:eval eval-expr datum ...)]]{ +@defform[(defexamples maybe-eval maybe-escape datum ...)]{ Like @racket[examples], but each definition using @racket[define] or @racket[define-struct] among the @racket[datum]s is typeset without a diff --git a/collects/scribblings/scribble/manual.scrbl b/collects/scribblings/scribble/manual.scrbl index b95527b029..537e0ac01b 100644 --- a/collects/scribblings/scribble/manual.scrbl +++ b/collects/scribblings/scribble/manual.scrbl @@ -97,7 +97,9 @@ produces the typeset result } -@defform[(racketblock datum ...)]{ +@defform/subs[(racketblock maybe-escape datum ...) + ([maybe-escape code:blank + (code:line #:escape escape-id)])]{ Typesets the @racket[datum] sequence as a table of Racket code inset inset via @racket[nested] with the style @racket['code-inset]. The @@ -120,20 +122,25 @@ produces the output with the @racket[(loop (not x))] indented under @racket[define], because that's the way it is idented the use of @racket[racketblock]. -Furthermore, @racket[define] is typeset as a keyword (bold and black) +Furthermore, @racket[define] is typeset as a keyword (in black) and as a hyperlink to @racket[define]'s definition in the reference manual, because this document was built using a for-label binding of @racket[define] (in the source) that matches a definition in the reference manual. Similarly, @racket[not] is a hyperlink to the its definition in the reference manual. -Use @racket[unsyntax] to escape back to an expression that produces an -@racket[element]. For example, +Like other forms defined via @racket[define-code], +@racket[racketblock] expands identifiers that are bound as +@tech{element transformers}. -@let[([unsyntax #f]) +An @racket[#:escape] clause specifies an identifier to escape back to +an expression that produces produces an @racket[element]. But default, +the escape identifier is @racket[unsyntax]. For example, + +@racketblock[ +#:escape nonesuch (racketblock - (racketblock - (+ 1 (unsyntax (elem (racket x) (subscript "2")))))) + (+ 1 (unsyntax (elem (racket x) (subscript "2"))))) ] produces @@ -142,9 +149,8 @@ produces (+ 1 (unsyntax (elem (racket x) (subscript "2")))) ] -The @racket[unsyntax] form is regonized via -@racket[free-identifier=?], so if you want to typeset code that -includes @racket[unsyntax], you can simply hide the usual binding: +The @racket[escape-id] that defaults to @racket[unsyntax] is regonized via +@racket[free-identifier=?], so a binding can hide the escape behavior: @RACKETBLOCK[ (racketblock @@ -153,7 +159,7 @@ includes @racket[unsyntax], you can simply hide the usual binding: (syntax (+ 1 (unsyntax x)))))) ] -Or use @racket[RACKETBLOCK], whose escape form is @racket[UNSYNTAX] +The @racket[RACKETBLOCK] form's default escape is @racket[UNSYNTAX] instead of @racket[unsyntax]. A few other escapes are recognized symbolically: @@ -199,41 +205,43 @@ A few other escapes are recognized symbolically: See also @racketmodname[scribble/comment-reader]. } -@defform[(RACKETBLOCK datum ...)]{Like @racket[racketblock], but with -the expression escape @racket[UNSYNTAX] instead of @racket[unsyntax].} +@defform[(RACKETBLOCK maybe-escape datum ...)]{Like @racket[racketblock], but with +the default expression escape @racket[UNSYNTAX] instead of @racket[unsyntax].} -@defform[(racketblock0 datum ...)]{Like @racket[racketblock], but +@defform[(racketblock0 maybe-escape datum ...)]{Like @racket[racketblock], but without insetting the code via @racket[nested].} -@defform[(RACKETBLOCK0 datum ...)]{Like @racket[RACKETBLOCK], but +@defform[(RACKETBLOCK0 maybe-escape datum ...)]{Like @racket[RACKETBLOCK], but without insetting the code via @racket[nested].} @deftogether[( -@defform[(racketresultblock datum ...)] -@defform[(racketresultblock0 datum ...)] -@defform[(RACKETRESULTBLOCK datum ...)] -@defform[(RACKETRESULTBLOCK0 datum ...)] +@defform[(racketresultblock maybe-escape datum ...)] +@defform[(racketresultblock0 maybe-escape datum ...)] +@defform[(RACKETRESULTBLOCK maybe-escape datum ...)] +@defform[(RACKETRESULTBLOCK0 maybe-escape datum ...)] )]{ Like @racket[racketblock], etc., but colors the typeset text as a result (i.e., a single color with no hyperlinks) instead of code.} @deftogether[( -@defform[(racketinput datum ...)] -@defform[(RACKETINPUT datum ...)] +@defform[(racketinput maybe-escape datum ...)] +@defform[(RACKETINPUT maybe-escape datum ...)] )]{Like @racket[racketblock] and @racket[RACKETBLOCK], but the @racket[datum]s are typeset after a prompt representing a REPL.} @deftogether[( -@defform[(racketinput0 datum ...)] -@defform[(RACKETINPUT0 datum ...)] +@defform[(racketinput0 maybe-escape datum ...)] +@defform[(RACKETINPUT0 maybe-escape datum ...)] )]{ Like @racket[racketinput] and @racket[RACKETINPUT], but without insetting the code via @racket[nested].} -@defform/subs[(racketmod maybe-file lang datum ...) +@defform/subs[(racketmod maybe-file maybe-escape lang datum ...) ([maybe-file code:blank - (code:line #:file filename-expr)])]{ + (code:line #:file filename-expr)] + [maybe-escape code:blank + (code:line #:escape escape-id)])]{ Like @racket[racketblock], but the @racket[datum] are typeset inside a @racketmodfont{#lang}-form module whose language is @racket[lang]. @@ -247,21 +255,21 @@ If @racket[#:file] is provided, then the code block is typeset using @racket[filebox] with @racket[filename-expr] as the filename argument.} -@defform[(racketmod0 maybe-file lang datum ...)]{ +@defform[(racketmod0 maybe-file maybe-escape lang datum ...)]{ Like @racket[racketmod], but without insetting the code via @racket[nested].} -@defform[(racket datum ...)]{Like @racket[racketblock], but typeset on +@defform[(racket maybe-escape datum ...)]{Like @racket[racketblock], but typeset on a single line and wrapped with its enclosing paragraph, independent of the formatting of @racket[datum].} -@defform[(RACKET datum ...)]{Like @racket[racket], but with the +@defform[(RACKET maybe-escape datum ...)]{Like @racket[racket], but with the @racket[UNSYNTAX] escape like @racket[racketblock].} -@defform[(racketresult datum ...)]{Like @racket[racket], but typeset +@defform[(racketresult maybe-escape datum ...)]{Like @racket[racket], but typeset as a result (i.e., a single color with no hyperlinks).} -@defform[(racketid datum ...)]{Like @racket[racket], but typeset +@defform[(racketid maybe-escape datum ...)]{Like @racket[racket], but typeset as an unbound identifier (i.e., no coloring or hyperlinks).} @defform*[((racketmodname datum) @@ -333,15 +341,15 @@ procedure, but use @racket[var] if that cannot work for some reason.} in a form definition.} @deftogether[( -@defform[(schemeblock datum ...)] -@defform[(SCHEMEBLOCK datum ...)] -@defform[(schemeblock0 datum ...)] -@defform[(SCHEMEBLOCK0 datum ...)] -@defform[(schemeinput datum ...)] -@defform[(schememod lang datum ...)] -@defform[(scheme datum ...)] -@defform[(SCHEME datum ...)] -@defform[(schemeresult datum ...)] +@defform[(schemeblock maybe-escape datum ...)] +@defform[(SCHEMEBLOCK maybe-escape datum ...)] +@defform[(schemeblock0 maybe-escape datum ...)] +@defform[(SCHEMEBLOCK0 maybe-escape datum ...)] +@defform[(schemeinput maybe-escape datum ...)] +@defform[(schememod lang maybe-escape datum ...)] +@defform[(scheme maybe-escape datum ...)] +@defform[(SCHEME maybe-escape datum ...)] +@defform[(schemeresult maybe-escape datum ...)] @defform[(schemeid datum ...)] @defform*[((schememodname datum) (schememodname ((unsyntax (racket unsyntax)) expr)))] diff --git a/collects/scribblings/scribble/scheme.scrbl b/collects/scribblings/scribble/scheme.scrbl index abf9b77b87..5a89221c70 100644 --- a/collects/scribblings/scribble/scheme.scrbl +++ b/collects/scribblings/scribble/scheme.scrbl @@ -17,8 +17,8 @@ interface.} Binds @racket[id] to a form similar to @racket[racket] or @racket[racketblock] for typesetting code. The form generated by @racket[define-code] handles source-location information, escapes via -@racket[unquote], preservation of binding and property information, -and @tech{element transformers}. +@racket[unquote] by default, preserves binding and property information, +and supports @tech{element transformers}. The supplied @racket[typeset-expr] expression should produce a procedure that performs the actual typesetting. This expression is @@ -26,8 +26,11 @@ normally @racket[to-element] or @racket[to-paragraph]. The argument supplied to @racket[typeset-expr] is normally a syntax object, but more generally it is the result of applying @racket[d->s-expr]. -The optional @racket[uncode-id] specifies the escape from literal code -to be recognized by @racket[id]. The default is @racket[unsyntax]. +The optional @racket[uncode-id] specifies the default escape from +literal code to be recognized by @racket[id], and the default for +@racket[uncode-id] is @racket[unsyntax]. A use of the @racket[id] form +can specify an alternate escape via @racket[#:escape], as in +@racket[racketblock] and @racket[racket]. The optional @racket[d->s-expr] should produce a procedure that accepts three arguments suitable for @racket[datum->syntax]: a syntax