From d4f25d8c72cf8399e922579ebd8983417d56e1c3 Mon Sep 17 00:00:00 2001
From: Vincent St-Amour <stamourv@racket-lang.org>
Date: Fri, 31 Jul 2015 12:17:43 -0500
Subject: [PATCH] Move syntax/macro-testing docs from unstable-doc.

---
 .../syntax/scribblings/macro-testing.scrbl    | 75 +++++++++++++++++++
 .../syntax/scribblings/syntax.scrbl           |  2 +
 2 files changed, 77 insertions(+)
 create mode 100644 pkgs/racket-doc/syntax/scribblings/macro-testing.scrbl

diff --git a/pkgs/racket-doc/syntax/scribblings/macro-testing.scrbl b/pkgs/racket-doc/syntax/scribblings/macro-testing.scrbl
new file mode 100644
index 0000000000..e1c6f39f4a
--- /dev/null
+++ b/pkgs/racket-doc/syntax/scribblings/macro-testing.scrbl
@@ -0,0 +1,75 @@
+#lang scribble/manual
+@(require scribble/eval
+          (for-label racket/base 
+                     racket/contract
+                     racket/struct-info
+                     rackunit
+                     syntax/macro-testing))
+
+@(define the-eval (make-base-eval))
+@(the-eval '(require rackunit syntax/macro-testing (for-syntax racket/base racket/struct-info)))
+
+@title[#:tag "macro-testing"]{Macro Testing}
+
+@defmodule[syntax/macro-testing]
+
+@defform/subs[(phase1-eval ct-expr maybe-quote maybe-catch?)
+              ([maybe-quote (code:line)
+                            (code:line #:quote quote-id)]
+               [maybe-catch? (code:line)
+                             (code:line #:catch? catch?)])]{
+
+Evaluates @racket[ct-expr] at compile time and quotes the result using
+@racket[quote-id], which defaults to @racket[quote]. Another suitable
+argument for @racket[quote-id] is @racket[quote-syntax].
+
+If @racket[catch?] is @racket[#t], then if the evaluation of
+@racket[ct-expr] raises a compile-time exception, it is caught and
+converted to a run-time exception.
+
+@examples[#:eval the-eval
+(struct point (x y))
+(phase1-eval (extract-struct-info (syntax-local-value #'point)))
+(phase1-eval (extract-struct-info (syntax-local-value #'point))
+             #:quote quote-syntax)
+]
+}
+
+@defform[(convert-compile-time-error expr)]{
+
+Equivalent to @racket[(#%expression expr)] except if expansion of
+@racket[expr] causes a compile-time exception to be raised; in that
+case, the compile-time exception is converted to a run-time exception
+raised when the expression is evaluated.
+
+Use @racket[convert-compile-time-error] to write tests for
+compile-time error checking like syntax errors:
+
+@examples[#:eval the-eval
+(check-exn #rx"missing an \"else\" expression"
+           (lambda () (convert-compile-time-error (if 1 2))))
+(check-exn #rx"missing formals and body"
+           (lambda () (convert-compile-time-error (lambda))))
+]
+
+Without the use of @racket[convert-compile-time-error], the checks
+above would not be executed because the test program would not compile.
+}
+
+@defform[(convert-syntax-error expr)]{
+
+Like @racket[convert-compile-time-error], but only catches compile-time
+@racket[exn:fail:syntax?] exceptions and sets
+@racket[error-print-source-location] to @racket[#f] around the
+expansion of @racket[expr] to make the message easier to match
+exactly.
+
+@examples[#:eval the-eval
+(check-exn #rx"^lambda: bad syntax$"
+           (lambda () (convert-syntax-error (lambda))))
+]
+
+@history[#:added "6.2.900.6"]{}
+}
+
+@(close-eval the-eval)
diff --git a/pkgs/racket-doc/syntax/scribblings/syntax.scrbl b/pkgs/racket-doc/syntax/scribblings/syntax.scrbl
index 5df8c32132..72458c85c8 100644
--- a/pkgs/racket-doc/syntax/scribblings/syntax.scrbl
+++ b/pkgs/racket-doc/syntax/scribblings/syntax.scrbl
@@ -33,4 +33,6 @@
 
 @include-section["contract.scrbl"]
 
+@include-section["macro-testing.scrbl"]
+
 @index-section[]