From e12b4a9088099ebd7d188fe494892a26a67d536c Mon Sep 17 00:00:00 2001
From: Matthew Flatt <mflatt@racket-lang.org>
Date: Sat, 9 Jun 2007 01:39:47 +0000
Subject: [PATCH] refine and document new scheme grammar forms

svn: r6551

original commit: 39a98d4266aea6f8fec455537c54b09fb1207642
---
 collects/scribble/manual.ss                | 21 +++++++++++--
 collects/scribblings/scribble/manual.scrbl | 35 +++++++++++++++-------
 2 files changed, 42 insertions(+), 14 deletions(-)

diff --git a/collects/scribble/manual.ss b/collects/scribble/manual.ss
index a7c85fdf..aa75b113 100644
--- a/collects/scribble/manual.ss
+++ b/collects/scribble/manual.ss
@@ -263,7 +263,10 @@
        (*defthing 'id 'result (lambda () (list desc ...)))]))
   (define-syntax schemegrammar
     (syntax-rules ()
-      [(_ id clause ...) (*schemegrammar (scheme id) (schemeblock0 clause) ...)]))
+      [(_ #:literals (lit ...) id clause ...) (*schemegrammar '(lit ...) 
+                                                              '(id clause ...)
+                                                              (lambda () (list (scheme id) (schemeblock0 clause) ...)))]
+      [(_ id clause ...) (schemegrammar #:literals () id clause ...)]))
   (define-syntax var
     (syntax-rules ()
       [(_ id) (*var 'id)]))
@@ -511,7 +514,7 @@
            append
            (map (lambda (sub)
                   (list (list (make-flow (list (make-paragraph (list (tt 'nbsp))))))
-                        (list (make-flow (list (apply *schemegrammar 
+                        (list (make-flow (list (apply *schemerawgrammar 
                                                       (map (lambda (f) (f)) sub)))))))
                 sub-procs))))
         (content-thunk)))))
@@ -540,7 +543,7 @@
                       (make-paragraph (list (to-element form)))))))))
         (flow-paragraphs (decode-flow (content-thunk)))))))
 
-  (define (*schemegrammar nonterm clause1 . clauses)
+  (define (*schemerawgrammar nonterm clause1 . clauses)
     (make-table
      '((valignment baseline baseline baseline baseline baseline)
        (alignment left left center left left))
@@ -560,6 +563,18 @@
                      (make-flow (list clause))))
              clauses)))))
 
+  (define (*schemegrammar lits s-expr clauses-thunk)
+    (parameterize ([current-variable-list
+                    (let loop ([form s-expr])
+                      (cond
+                       [(symbol? form) (if (memq form lits)
+                                           null
+                                           (list form))]
+                       [(pair? form) (append (loop (car form))
+                                             (loop (cdr form)))]
+                       [else null]))])
+      (apply *schemerawgrammar (clauses-thunk))))
+
   (define (*var id)
     (to-element (*var-sym id)))
 
diff --git a/collects/scribblings/scribble/manual.scrbl b/collects/scribblings/scribble/manual.scrbl
index 5efabab0..cf90c5ee 100644
--- a/collects/scribblings/scribble/manual.scrbl
+++ b/collects/scribblings/scribble/manual.scrbl
@@ -226,6 +226,18 @@ procedure. In this description, a reference to any identifier in
 The typesetting of @scheme[(id . datum)] preserves the source
 layout, like @scheme[schemeblock], and unlike @scheme[defproc].}
 
+@defform[(defform* [(id . datum) ..+] pre-flow ...)]{Like @scheme[defform],
+but for multiple forms using the same @scheme[id].}
+
+@defform[(defform/subs (id . datum) 
+           ([nonterm-id clause-datum ...+] ...) 
+           pre-flow ...)]{
+Like @scheme[defform], but including an auxiliary grammar of
+non-terminals shown with the @scheme[id] form. Each
+@scheme[nonterm-id] is specified as being any of the corresponding
+@scheme[clause-datum]s, where the formatting of each
+@scheme[clause-datum] is preserved.}
+
 @defform[(specform (id . datum) pre-flow ...)]{Like @scheme[defform],
 with without registering a definition, and with indenting on the left
 for both the specification and the @scheme[pre-flow]s.}
@@ -242,22 +254,23 @@ The @scheme[pre-flow]s list is parsed as a flow that documents the
 procedure. In this description, a reference to any identifier in
 @scheme[datum] is typeset as a sub-form non-terminal.}
 
-
 @defform[(defthing id contract-expr-datum pre-flow ...)]{Like
 @scheme[defproc], but for a non-procedure binding.}
 
-@defform[(defstruct struct-name ([field-name contract-expr-datum] ...) 
-                    pre-flow ...)]{
+@defform/subs[(defstruct struct-name ([field-name contract-expr-datum] ...)
+                pre-flow ...)
+              ([struct-name id
+                            (id super-id)])]{
 
-Similar to @scheme[defform], but for a structure definition.
-
-The @scheme[struct-name] can be either of the following:
-
-@specsubform[id]{A structure type with no
-       specified supertype.}
-
-@specsubform[(id super-id)]{A type with indicated supertype.}
+Similar to @scheme[defform] or @scheme[defproc], but for a structure
+definition.}
 
+@defform/subs[(schemegrammar literals ? id clause-datum ...+)
+              ([literals (code:line #:literals (literal-id ...))])]{
+Creates a table to define the grammar of @scheme[id]. Each identifier mentioned
+in a @scheme[clause-datum] is typeset as a non-terminal, except for the
+identifiers listed as @scheme[literal-id]s, which are typeset as with 
+@scheme[scheme].
 }
 
 @; ------------------------------------------------------------------------