diff --git a/scribble-doc/scribblings/scribble/examples.scrbl b/scribble-doc/scribblings/scribble/examples.scrbl index 76362a33..bef2633f 100644 --- a/scribble-doc/scribblings/scribble/examples.scrbl +++ b/scribble-doc/scribblings/scribble/examples.scrbl @@ -117,8 +117,7 @@ Certain patterns in @racket[datum] are treated specially: @racket[(@#,indexed-racket[eval:error] #,(svar eval-datum))] is treated like @racket[_eval-datum], but @racket[_eval-datum] is expected to raise an exception, and an error is shown as the - evaluation's result---even if @racket[#:no-errors? #t] is - specified for the @racket[interactions] form.} + evaluation's result.} @item{A @racket[datum] of the form @racket[(@#,indexed-racket[eval:alts] #,(svar show-datum) #,(svar eval-datum))] @@ -138,7 +137,9 @@ Certain patterns in @racket[datum] are treated specially: in which case they default to empty strings. Normally, @racketidfont{eval:result} - is used in the second part of an @racketidfont{eval:alts} combination.} + is used in the second part of an @racketidfont{eval:alts} combination. Otherwise, + @racket[_content-expr] is typeset as the input form (which rarely makes sense for + a reader of the example).} @item{A @racket[datum] of the form @racket[(@#,indexed-racket[eval:results] _content-list-expr _out-expr _err-expr)] diff --git a/scribble-lib/scribble/eval.rkt b/scribble-lib/scribble/eval.rkt index dc70f15f..69b576c9 100644 --- a/scribble-lib/scribble/eval.rkt +++ b/scribble-lib/scribble/eval.rkt @@ -705,18 +705,22 @@ [(_ e ...) (do-interaction-eval-show #f (list (quote-expr e) ...))])) (define-syntax racketinput* - (syntax-rules (eval:alts code:comment eval:check eval:no-prompt eval:error) + (syntax-rules (eval:alts code:comment eval:check eval:no-prompt eval:error eval:result eval:results) [(_ #:escape id (code:comment . rest)) (racketblock0 #:escape id (code:comment . rest))] [(_ #:escape id (eval:alts a b)) (racketinput* #:escape id a)] + [(_ #:escape id (eval:result a . _)) (racketinput* #:escape id a)] + [(_ #:escape id (eval:results a . _)) (racketinput* #:escape id a)] [(_ #:escape id (eval:check a b)) (racketinput* #:escape id a)] [(_ #:escape id (eval:error a)) (racketinput* #:escape id a)] [(_ #:escape id (eval:no-prompt a ...)) (racketblock* #:escape id (code:line a ...))] [(_ #:escape id e) (racketinput0 #:escape id e)])) (define-syntax racketblock* - (syntax-rules (eval:alts code:comment eval:check eval:no-prompt eval:error) + (syntax-rules (eval:alts code:comment eval:check eval:no-prompt eval:error eval:result eval:results) [(_ #:escape id (code:comment . rest)) (racketblock0 #:escape id (code:comment . rest))] [(_ #:escape id (eval:alts a b)) (racketblock #:escape id a)] + [(_ #:escape id (eval:result a . _)) (racketinputblock #:escape id a)] + [(_ #:escape id (eval:results a . _)) (racketinputblock #:escape id a)] [(_ #:escape id (eval:check a b)) (racketblock #:escape id a)] [(_ #:escape id (eval:no-prompt a ...)) (racketblock #:escape id (code:line a ...))] [(_ #:escape id (eval:error a)) (racketblock #:escape id a)] diff --git a/scribble-test/tests/scribble/docs/eval-special.txt b/scribble-test/tests/scribble/docs/eval-special.txt index 30072833..418139be 100644 --- a/scribble-test/tests/scribble/docs/eval-special.txt +++ b/scribble-test/tests/scribble/docs/eval-special.txt @@ -1,22 +1,22 @@ - > (+ 1 2) - 3 - > (+ 1 2) ; three - 3 - > (+ 1 2) - 5 - > (eval:result (bold "example")) - example - > (+ 1 2) - same - > (+ 1 2) - Again... - really the same - > (+ 1 2) - ! - error: too many repeats - still the same - > (+ 1 2) - counting - 1 - 2 - 3 + > (+ 1 2) + 3 + > (+ 1 2) ; three + 3 + > (+ 1 2) + 5 + > (bold "example") + example + > (+ 1 2) + same + > (+ 1 2) + Again... + really the same + > (+ 1 2) + ! + error: too many repeats + still the same + > (+ 1 2) + counting + 1 + 2 + 3 diff --git a/scribble-test/tests/scribble/docs/examples.scrbl b/scribble-test/tests/scribble/docs/examples.scrbl new file mode 100644 index 00000000..31f5e9b0 --- /dev/null +++ b/scribble-test/tests/scribble/docs/examples.scrbl @@ -0,0 +1,93 @@ +#lang scribble/base +@(require scribble/examples) + +@(define shared-eval (make-base-eval)) +@examples[#:hidden #:eval shared-eval "just testing"] + +@examples[ +(+ 1 2) +] + +@examples[ +(+ 3 4) +(string-append "5" + "6") +] + +@examples[ +#:label #f +(+ 2 3) +] + +@examples[ +#:label "Another example:" +(+ 2 4) +] + +@examples[ +#:no-inset +(+ 2 5) +(* 3 4) +] + +@examples[ +#:no-prompt +(+ 2 6) +(* 3 5) +] + +@examples[ +#:result-only +"Just the result."] + +@examples[ +#:preserve-source-locations +(syntax-line (quote-syntax here)) +] + +@examples[ +#:no-result +"don't show the result" +] + +@examples[ +#:lang racket/base +(define x "don't show") +"the result" +] + +@examples[ +(eval:error (/ 1 0)) +] + +@examples[ +(code:line (+ 1 2) (* 3 4)) +] + +@examples[ +(eval:check (+ 1 2) (* 3 1)) +] + +@examples[ +(eval:alts (/ 1 0) +inf.0) +] + +@examples[ +(eval:result "(/ 1 0)") +] + +@examples[ +(eval:result "(/ 1 0)" "getting +inf.0") +] + +@examples[ +(eval:result "(/ 1 0)" "getting +inf.0" "oops") +] + +@examples[ +(eval:alts (/ 100 0) (eval:result "(/ 1 0)" "getting +inf.0" "oops")) +] + +@examples[ +(eval:alts (/ 100 0) (eval:results (list "(/ 1 0)" "'=") "getting +inf.0" "oops")) +] diff --git a/scribble-test/tests/scribble/docs/examples.txt b/scribble-test/tests/scribble/docs/examples.txt new file mode 100644 index 00000000..6d2b03b3 --- /dev/null +++ b/scribble-test/tests/scribble/docs/examples.txt @@ -0,0 +1,100 @@ +Example: + + > (+ 1 2) + 3 + +Examples: + + > (+ 3 4) + 7 + > (string-append "5" +                  "6") + "56" + + > (+ 2 3) + 5 + +Another example: + + > (+ 2 4) + 6 + +Examples: + +> (+ 2 5) +7 +> (* 3 4) +12 + +Examples: + + (+ 2 6) + 8 + (* 3 5) + 15 + +"Just the result." + +Example: + + > (syntax-line (quote-syntax here)) + 45 + + "don't show the result" + + #lang racket/base + (define x "don't show") + "the result" + +Example: + + > (/ 1 0) + /: division by zero + +Example: + + > (+ 1 2) (* 3 4) + 12 + +Example: + + > (+ 1 2) + 3 + +Example: + + > (/ 1 0) + +inf.0 + +Example: + + > "(/ 1 0)" + (/ 1 0) + +Example: + + > "(/ 1 0)" + getting +inf.0 + (/ 1 0) + +Example: + + > "(/ 1 0)" + getting +inf.0 + oops + (/ 1 0) + +Example: + + > (/ 100 0) + getting +inf.0 + oops + (/ 1 0) + +Example: + + > (/ 100 0) + getting +inf.0 + oops + (/ 1 0) + '=