From 2eae24b0b1b4e84dc8db3a2001e24ce1e8f2b2eb Mon Sep 17 00:00:00 2001
From: Ryan Culpepper <ryanc@racket-lang.org>
Date: Wed, 20 Mar 2013 21:49:37 -0400
Subject: [PATCH] use defform #:grammar

---
 .../scribblings/parse/experimental.scrbl      |  77 ++++++-----
 .../syntax/scribblings/parse/litconv.scrbl    |  40 +++---
 .../syntax/scribblings/parse/parsing.scrbl    |  74 +++++-----
 .../syntax/scribblings/parse/patterns.scrbl   | 127 ++++++++++--------
 .../syntax/scribblings/parse/stxclasses.scrbl |  65 ++++-----
 5 files changed, 203 insertions(+), 180 deletions(-)

diff --git a/collects/syntax/scribblings/parse/experimental.scrbl b/collects/syntax/scribblings/parse/experimental.scrbl
index af938e50b2..a05b647f8b 100644
--- a/collects/syntax/scribblings/parse/experimental.scrbl
+++ b/collects/syntax/scribblings/parse/experimental.scrbl
@@ -20,15 +20,16 @@ compatibility.
 
 @defmodule[syntax/parse/experimental/provide]
 
-@defform/subs[#:literals (syntax-class/c)
-              (provide-syntax-class/contract
-                [syntax-class-id syntax-class-contract] ...)
-              ([syntax-class-contract
-                (syntax-class/c (mandatory-arg ...))
-                (syntax-class/c (mandatory-arg ...)
-                                (optional-arg ...))]
-               [arg contract-expr (code:line keyword contract-expr)])
-              #:contracts ([contract-expr contract?])]{
+@defform[#:literals (syntax-class/c)
+         (provide-syntax-class/contract
+           [syntax-class-id syntax-class-contract] ...)
+         #:grammar
+         ([syntax-class-contract
+           (syntax-class/c (mandatory-arg ...))
+           (syntax-class/c (mandatory-arg ...)
+                           (optional-arg ...))]
+          [arg contract-expr (code:line keyword contract-expr)])
+         #:contracts ([contract-expr contract?])]{
 
 Provides the syntax class (or splicing syntax class)
 @racket[syntax-class-id] with the given contracts imposed on its
@@ -101,9 +102,10 @@ error is raised.
                            (~splicing-reflect var-id (reified-expr arg-expr ...)
                                               maybe-attrs)]]
 
-@specsubform/subs[(@#,(defhere ~reflect) var-id (reified-expr arg-expr ...) maybe-attrs)
-                  ([maybe-attrs (code:line)
-                                (code:line #:attributes (attr-arity-decl ...))])]{
+@specsubform[(@#,(defhere ~reflect) var-id (reified-expr arg-expr ...) maybe-attrs)
+             #:grammar
+         ([maybe-attrs (code:line)
+                                  (code:line #:attributes (attr-arity-decl ...))])]{
 
 Like @racket[~var], except that the syntax class position is an
 expression evaluating to a reified syntax object, not a syntax class
@@ -189,9 +191,10 @@ sets of terms but also repetition constraints.
 This module provides @deftech{ellipsis-head alternative sets},
 reusable encapsulations of @|EHpatterns|.
 
-@defform/subs[#:literals (pattern)
-              (define-eh-alternative-set name eh-alternative ...)
-              ([alternative (pattern EH-pattern)])]{
+@defform[#:literals (pattern)
+         (define-eh-alternative-set name eh-alternative ...)
+         #:grammar
+         ([alternative (pattern EH-pattern)])]{
 
 Defines @racket[name] as an ellipsis-head alternative set. Using
 @racket[name] (via @racket[~eh-var]) in an ellipsis-head pattern is
@@ -246,11 +249,12 @@ their attributes with @racket[name].
 
 @defmodule[syntax/parse/experimental/specialize]
 
-@defform/subs[(define-syntax-class/specialize header syntax-class-use)
-              ([header id
-                       (id . kw-formals)]
-               [syntax-class-use target-stxclass-id
-                                 (target-stxclass-id arg ...)])]{
+@defform[(define-syntax-class/specialize header syntax-class-use)
+         #:grammar
+         ([header id
+                  (id . kw-formals)]
+          [syntax-class-use target-stxclass-id
+                            (target-stxclass-id arg ...)])]{
 
 Defines @racket[id] as a syntax class with the same attributes,
 options (eg, @racket[#:commit], @racket[#:no-delimit-cut]), and
@@ -272,22 +276,23 @@ patterns as @racket[target-stxclass-id] but with the given
 
 @(define literal-ellipsis (racket ...))
 
-@defform/subs[#:literals (?? ?@)
-              (template tmpl)
-              ([tmpl pattern-variable-id
-                     (head-tmpl . tmpl)
-                     (head-tmpl ellipsis ...+ . tmpl)
-                     (metafunction-id . tmpl)
-                     (?? tmpl tmpl)
-                     #(@#,svar[head-tmpl] ...)
-                     #s(prefab-struct-key @#,svar[head-tmpl] ...)
-                     #&@#,svar[tmpl]
-                     constant-term]
-               [head-templ tmpl
-                           (?? head-tmpl)
-                           (?? head-tmpl head-tmpl)
-                           (?@ . tmpl)]
-               [ellipsis @#,literal-ellipsis])]{
+@defform[#:literals (?? ?@)
+         (template tmpl)
+         #:grammar
+         ([tmpl pattern-variable-id
+                (head-tmpl . tmpl)
+                (head-tmpl ellipsis ...+ . tmpl)
+                (metafunction-id . tmpl)
+                (?? tmpl tmpl)
+                #(@#,svar[head-tmpl] ...)
+                #s(prefab-struct-key @#,svar[head-tmpl] ...)
+                #&@#,svar[tmpl]
+                constant-term]
+          [head-templ tmpl
+                      (?? head-tmpl)
+                      (?? head-tmpl head-tmpl)
+                      (?@ . tmpl)]
+          [ellipsis @#,literal-ellipsis])]{
 
 Constructs a syntax object from a syntax template, like
 @racket[syntax], but provides additional templating forms for dealing
diff --git a/collects/syntax/scribblings/parse/litconv.scrbl b/collects/syntax/scribblings/parse/litconv.scrbl
index d8a56e4450..7a8b047364 100644
--- a/collects/syntax/scribblings/parse/litconv.scrbl
+++ b/collects/syntax/scribblings/parse/litconv.scrbl
@@ -15,19 +15,20 @@ As a remedy, @racketmodname[syntax/parse] offers @deftech{literal
 sets}. A literal set is defined via @racket[define-literal-set] and
 used via the @racket[#:literal-set] option of @racket[syntax-parse].
 
-@defform/subs[(define-literal-set id maybe-phase maybe-imports maybe-datum-literals
-                (literal ...))
-              ([literal literal-id
-                        (pattern-id literal-id)]
-               [maybe-phase (code:line)
-                            (code:line #:for-template)
-                            (code:line #:for-syntax)
-                            (code:line #:for-label)
-                            (code:line #:phase phase-level)]
-               [maybe-datum-literals (code:line)
-                                     (code:line #:datum-literals (datum-literal ...))]
-               [maybe-imports (code:line)
-                              (code:line #:literal-sets (imported-litset-id ...))])]{
+@defform[(define-literal-set id maybe-phase maybe-imports maybe-datum-literals
+           (literal ...))
+         #:grammar
+          ([literal literal-id
+                    (pattern-id literal-id)]
+           [maybe-phase (code:line)
+                        (code:line #:for-template)
+                        (code:line #:for-syntax)
+                        (code:line #:for-label)
+                        (code:line #:phase phase-level)]
+           [maybe-datum-literals (code:line)
+                                 (code:line #:datum-literals (datum-literal ...))]
+           [maybe-imports (code:line)
+                          (code:line #:literal-sets (imported-litset-id ...))])]{
 
 Defines @racket[id] as a @tech{literal set}. Each @racket[literal] can
 have a separate @racket[pattern-id] and @racket[literal-id]. The
@@ -114,12 +115,13 @@ the @racket[_phase] argument defaults to
 ]
 }
 
-@defform/subs[(define-conventions name-id convention-rule ...)
-              ([convention-rule (name-pattern syntax-class)]
-               [name-pattern exact-id
-                             name-rx]
-               [syntax-class syntax-class-id
-                             (syntax-class-id expr ...)])]{
+@defform[(define-conventions name-id convention-rule ...)
+         #:grammar
+         ([convention-rule (name-pattern syntax-class)]
+          [name-pattern exact-id
+                        name-rx]
+          [syntax-class syntax-class-id
+                        (syntax-class-id expr ...)])]{
 
 Defines @deftech{conventions} that supply default syntax classes for
 pattern variables. A pattern variable that has no explicit syntax
diff --git a/collects/syntax/scribblings/parse/parsing.scrbl b/collects/syntax/scribblings/parse/parsing.scrbl
index 732cb0b27f..41d253c7e8 100644
--- a/collects/syntax/scribblings/parse/parsing.scrbl
+++ b/collects/syntax/scribblings/parse/parsing.scrbl
@@ -20,27 +20,28 @@ of @tech{syntax patterns}, which is described in detail in
 Two parsing forms are provided: @racket[syntax-parse] and
 @racket[syntax-parser].
 
-@defform/subs[(syntax-parse stx-expr parse-option ... clause ...+)
-              ([parse-option (code:line #:context context-expr)
-                             (code:line #:literals (literal ...))
-                             (code:line #:datum-literals (datum-literal ...))
-                             (code:line #:literal-sets (literal-set ...))
-                             (code:line #:conventions (convention-id ...))
-                             (code:line #:local-conventions (convention-rule ...))
-                             (code:line #:disable-colon-notation)]
-               [literal literal-id
-                        (pattern-id literal-id)
-                        (pattern-id literal-id #:phase phase-expr)]
-               [datum-literal literal-id
-                              (pattern-id literal-id)]
-               [literal-set literal-set-id
-                            (literal-set-id literal-set-option ...)]
-               [literal-set-option (code:line #:at context-id)
-                                   (code:line #:phase phase-expr)]
-               [clause (syntax-pattern pattern-directive ... body ...+)])
-              #:contracts ([stx-expr syntax?]
-                           [context-expr syntax?]
-                           [phase-expr (or/c exact-integer? #f)])]{
+@defform[(syntax-parse stx-expr parse-option ... clause ...+)
+         #:grammar
+         ([parse-option (code:line #:context context-expr)
+                        (code:line #:literals (literal ...))
+                        (code:line #:datum-literals (datum-literal ...))
+                        (code:line #:literal-sets (literal-set ...))
+                        (code:line #:conventions (convention-id ...))
+                        (code:line #:local-conventions (convention-rule ...))
+                        (code:line #:disable-colon-notation)]
+          [literal literal-id
+                   (pattern-id literal-id)
+                   (pattern-id literal-id #:phase phase-expr)]
+          [datum-literal literal-id
+                         (pattern-id literal-id)]
+          [literal-set literal-set-id
+                       (literal-set-id literal-set-option ...)]
+          [literal-set-option (code:line #:at context-id)
+                              (code:line #:phase phase-expr)]
+          [clause (syntax-pattern pattern-directive ... body ...+)])
+         #:contracts ([stx-expr syntax?]
+                      [context-expr syntax?]
+                      [phase-expr (or/c exact-integer? #f)])]{
 
 Evaluates @racket[stx-expr], which should produce a syntax object, and
 matches it against the @racket[clause]s in order. If some clause's
@@ -74,11 +75,12 @@ failures; otherwise @racket[stx-expr] is used. The
     [(x:id ...) 'ok]))
 }
 
-@specsubform/subs[(code:line #:literals (literal ...))
-                  ([literal literal-id
-                            (pattern-id literal-id)
-                            (pattern-id literal-id #:phase phase-expr)])
-                  #:contracts ([phase-expr (or/c exact-integer? #f)])]{
+@specsubform[(code:line #:literals (literal ...))
+             #:grammar
+             ([literal literal-id
+                       (pattern-id literal-id)
+                       (pattern-id literal-id #:phase phase-expr)])
+             #:contracts ([phase-expr (or/c exact-integer? #f)])]{
 
 @margin-note*{
   Unlike @racket[syntax-case], @racket[syntax-parse] requires all
@@ -105,9 +107,10 @@ occurrence of @racket[pattern-id] were replaced with the following pattern:
 @racketblock[(~literal literal-id #:phase phase-expr)]
 }
 
-@specsubform/subs[(code:line #:datum-literals (datum-literal ...))
-                  ([datum-literal literal-id
-                                  (pattern-id literal-id)])]{
+@specsubform[(code:line #:datum-literals (datum-literal ...))
+             #:grammar
+             ([datum-literal literal-id
+                             (pattern-id literal-id)])]{
 
 Like @racket[#:literals], but the literals are matched as symbols
 instead of as identifiers.
@@ -118,12 +121,13 @@ pattern:
 @racketblock[(~datum literal-id)]
 }
 
-@specsubform/subs[(code:line #:literal-sets (literal-set ...))
-                  ([literal-set literal-set-id
-                                (literal-set-id literal-set-option ...)]
-                   [literal-set-option (code:line #:at lctx)
-                                       (code:line #:phase phase-expr)])
-                  #:contracts ([phase-expr (or/c exact-integer? #f)])]{
+@specsubform[(code:line #:literal-sets (literal-set ...))
+             #:grammar
+             ([literal-set literal-set-id
+                           (literal-set-id literal-set-option ...)]
+              [literal-set-option (code:line #:at lctx)
+                                  (code:line #:phase phase-expr)])
+             #:contracts ([phase-expr (or/c exact-integer? #f)])]{
 
 Many literals can be declared at once via one or more @tech{literal
 sets}, imported with the @racket[#:literal-sets] option. See
diff --git a/collects/syntax/scribblings/parse/patterns.scrbl b/collects/syntax/scribblings/parse/patterns.scrbl
index 5590e1a57a..d3caec4c03 100644
--- a/collects/syntax/scribblings/parse/patterns.scrbl
+++ b/collects/syntax/scribblings/parse/patterns.scrbl
@@ -260,12 +260,13 @@ like an @tech{annotated pattern variable} with the implicit syntax
 class inserted.
 }
 
-@specsubform/subs[(@#,def[~var s+] pvar-id syntax-class-use maybe-role)
-                  ([syntax-class-use syntax-class-id
-                                     (syntax-class-id arg ...)]
-                   [maybe-role (code:line)
-                               (code:line #:role role-expr)])
-                  #:contracts ([role-expr (or/c string? #f)])]{
+@specsubform[(@#,def[~var s+] pvar-id syntax-class-use maybe-role)
+             #:grammar
+             ([syntax-class-use syntax-class-id
+                                (syntax-class-id arg ...)]
+              [maybe-role (code:line)
+                          (code:line #:role role-expr)])
+             #:contracts ([role-expr (or/c string? #f)])]{
 
 An @deftech{annotated pattern variable}. The pattern matches only
 terms accepted by @svar[syntax-class-id] (parameterized by the
@@ -305,9 +306,10 @@ combined with the syntax class's description in error messages.
 ]
 }
 
-@specsubform/subs[(@#,defhere[~literal] literal-id maybe-phase)
-                  ([maybe-phase (code:line)
-                                (code:line #:phase phase-expr)])]{
+@specsubform[(@#,defhere[~literal] literal-id maybe-phase)
+             #:grammar
+             ([maybe-phase (code:line)
+                           (code:line #:phase phase-expr)])]{
 
 A @deftech{literal} identifier pattern. Matches any identifier
 @racket[free-identifier=?] to @racket[literal-id].
@@ -557,13 +559,14 @@ above).
 ]
 }
 
-@specsubform/subs[(@#,def[~describe s] maybe-opaque expr S-pattern)
-                  ([maybe-opaque (code:line)
-                                 (code:line #:opaque)]
-                   [maybe-role (code:line)
-                               (code:line #:role role-expr)])
-                  #:contracts ([expr (or/c string? #f)]
-                               [role-expr (or/c string? #f)])]{
+@specsubform[(@#,def[~describe s] maybe-opaque expr S-pattern)
+             #:grammar
+             ([maybe-opaque (code:line)
+                            (code:line #:opaque)]
+              [maybe-role (code:line)
+                          (code:line #:role role-expr)])
+             #:contracts ([expr (or/c string? #f)]
+                          [role-expr (or/c string? #f)])]{
 
 The @racket[~describe] pattern form annotates a pattern with a
 description, a string expression that is evaluated in the scope of all
@@ -647,12 +650,13 @@ Equivalent to @racket[(~var pvar-id splicing-syntax-class-id)].
 
 }
 
-@specsubform/subs[(@#,def[~var h] pvar-id splicing-syntax-class-use maybe-role)
-                  ([splicing-syntax-class-use splicing-syntax-class-id
-                                              (splicing-syntax-class-id arg ...)]
-                   [maybe-role (code:line)
-                               (code:line #:role role-expr)])
-                  #:contracts ([role-expr (or/c string? #f)])]{
+@specsubform[(@#,def[~var h] pvar-id splicing-syntax-class-use maybe-role)
+             #:grammar
+             ([splicing-syntax-class-use splicing-syntax-class-id
+                                         (splicing-syntax-class-id arg ...)]
+              [maybe-role (code:line)
+                          (code:line #:role role-expr)])
+             #:contracts ([role-expr (or/c string? #f)])]{
 
 Pattern variable annotated with a @tech{splicing syntax
 class}. Similar to a normal @tech{annotated pattern variable}, except
@@ -721,13 +725,14 @@ terms instead.
 ]
 }
 
-@specsubform/subs[(@#,def[~optional h] H-pattern maybe-optional-option)
-                  ([maybe-optional-option
-                    (code:line)
-                    (code:line #:defaults ([attr-arity-decl expr] ...))]
-                   [attr-arity-decl
-                    attr-id
-                    (attr-id depth)])]{
+@specsubform[(@#,def[~optional h] H-pattern maybe-optional-option)
+             #:grammar
+             ([maybe-optional-option
+                (code:line)
+                (code:line #:defaults ([attr-arity-decl expr] ...))]
+              [attr-arity-decl
+                attr-id
+                (attr-id depth)])]{
 
 Matches either the given head subpattern or an empty sequence of
 terms. If the @racket[#:defaults] option is given, the subsequent
@@ -847,13 +852,14 @@ Here are the variants of @elem{@EHpattern}:
 Matches if any of the inner @racket[EH-pattern] alternatives match.
 }
 
-@specsubform/subs[(@#,defhere[~once] H-pattern once-option ...)
-                  ([once-option (code:line #:name name-expr)
-                                (code:line #:too-few too-few-message-expr)
-                                (code:line #:too-many too-many-message-expr)])
-                  #:contracts ([name-expr (or/c string? #f)]
-                               [too-few-message-expr (or/c string? #f)]
-                               [too-many-message-expr (or/c string? #f)])]{
+@specsubform[(@#,defhere[~once] H-pattern once-option ...)
+             #:grammar
+             ([once-option (code:line #:name name-expr)
+                           (code:line #:too-few too-few-message-expr)
+                           (code:line #:too-many too-many-message-expr)])
+             #:contracts ([name-expr (or/c string? #f)]
+                          [too-few-message-expr (or/c string? #f)]
+                          [too-many-message-expr (or/c string? #f)])]{
 
 Matches if the inner @racket[H-pattern] matches. This pattern must be
 matched exactly once in the match of the entire repetition sequence.
@@ -869,12 +875,13 @@ then the ellipsis pattern fails with the message either
 of @racket[name-expr]"}.
 }
 
-@specsubform/subs[(@#,def[~optional eh] H-pattern optional-option ...)
-                  ([optional-option (code:line #:name name-expr)
-                                    (code:line #:too-many too-many-message-expr)
-                                    (code:line #:defaults ([attr-id expr] ...))])
-                  #:contracts ([name-expr (or/c string? #f)]
-                               [too-many-message-expr (or/c string? #f)])]{
+@specsubform[(@#,def[~optional eh] H-pattern optional-option ...)
+             #:grammar
+             ([optional-option (code:line #:name name-expr)
+                               (code:line #:too-many too-many-message-expr)
+                               (code:line #:defaults ([attr-id expr] ...))])
+             #:contracts ([name-expr (or/c string? #f)]
+                          [too-many-message-expr (or/c string? #f)])]{
 
 Matches if the inner @racket[H-pattern] matches. This pattern may be used at
 most once in the match of the entire repetition.
@@ -890,12 +897,13 @@ sequence. The default attributes must be a subset of the subpattern's
 attributes.
 }
 
-@specsubform/subs[(@#,defhere[~between] H-pattern min-number max-number between-option ...)
-                  ([reps-option (code:line #:name name-expr)
-                                (code:line #:too-few too-few-message-expr)
-                                (code:line #:too-many too-many-message-expr)])
-                  #:contracts ([name-expr (or/c syntax? #f)]
-                               [too-few-message-expr (or/c syntax? #f)])]{
+@specsubform[(@#,defhere[~between] H-pattern min-number max-number between-option ...)
+             #:grammar
+             ([reps-option (code:line #:name name-expr)
+                           (code:line #:too-few too-few-message-expr)
+                           (code:line #:too-many too-many-message-expr)])
+             #:contracts ([name-expr (or/c syntax? #f)]
+                          [too-few-message-expr (or/c syntax? #f)])]{
 
 Matches if the inner @racket[H-pattern] matches. This pattern must be
 matched at least @racket[min-number] and at most @racket[max-number]
@@ -966,22 +974,23 @@ within a @racket[~not] pattern unless there is an intervening
 @racket[~delimit-cut] or @racket[~commit] pattern.
 }
 
-@specsubform/subs[(@#,defhere[~bind] [attr-arity-decl expr] ...)
-                  ([attr-arity-decl
-                    attr-name-id
-                    (attr-name-id depth)])]{
+@specsubform[(@#,defhere[~bind] [attr-arity-decl expr] ...)
+             #:grammar
+             ([attr-arity-decl attr-name-id
+                               (attr-name-id depth)])]{
 
 Evaluates the @racket[expr]s and binds them to the given
 @racket[attr-id]s as attributes.
 }
 
-@specsubform/subs[(@#,defhere[~fail] maybe-fail-condition maybe-message-expr)
-                  ([maybe-fail-condition (code:line)
-                                         (code:line #:when condition-expr)
-                                         (code:line #:unless condition-expr)]
-                   [maybe-message-expr (code:line)
-                                       (code:line message-expr)])
-                  #:contracts ([message-expr (or/c string? #f)])]{
+@specsubform[(@#,defhere[~fail] maybe-fail-condition maybe-message-expr)
+             #:grammar
+             ([maybe-fail-condition (code:line)
+                                    (code:line #:when condition-expr)
+                                    (code:line #:unless condition-expr)]
+              [maybe-message-expr (code:line)
+                                  (code:line message-expr)])
+             #:contracts ([message-expr (or/c string? #f)])]{
 
 If the condition is absent, or if the @racket[#:when] condition
 evaluates to a true value, or if the @racket[#:unless] condition
diff --git a/collects/syntax/scribblings/parse/stxclasses.scrbl b/collects/syntax/scribblings/parse/stxclasses.scrbl
index 05247d46c6..ed2189aa4b 100644
--- a/collects/syntax/scribblings/parse/stxclasses.scrbl
+++ b/collects/syntax/scribblings/parse/stxclasses.scrbl
@@ -17,29 +17,30 @@ complex syntax, such as lists of distinct identifiers and formal
 arguments with keywords. Macros that manipulate the same syntactic
 structures can share syntax class definitions.
 
-@defform*/subs[#:literals (pattern)
-               [(define-syntax-class name-id stxclass-option ...
-                  stxclass-variant ...+)
-                (define-syntax-class (name-id . kw-formals) stxclass-option ... 
-                  stxclass-variant ...+)]
-               ([stxclass-option
-                 (code:line #:attributes (attr-arity-decl ...))
-                 (code:line #:description description-expr)
-                 (code:line #:opaque)
-                 (code:line #:commit)
-                 (code:line #:no-delimit-cut)
-                 (code:line #:literals (literal-entry ...))
-                 (code:line #:datum-literals (datum-literal-entry ...))
-                 (code:line #:literal-sets (literal-set ...))
-                 (code:line #:conventions (convention-id ...))
-                 (code:line #:local-conventions (convention-rule ...))
-                 (code:line #:disable-colon-notation)]
-                [attr-arity-decl
-                 attr-name-id
-                 (attr-name-id depth)]
-                [stxclass-variant
-                 (pattern syntax-pattern pattern-directive ...)])
-               #:contracts ([description-expr (or/c string? #f)])]{
+@defform*[#:literals (pattern)
+          [(define-syntax-class name-id stxclass-option ...
+             stxclass-variant ...+)
+           (define-syntax-class (name-id . kw-formals) stxclass-option ... 
+             stxclass-variant ...+)]
+          #:grammar
+          ([stxclass-option
+            (code:line #:attributes (attr-arity-decl ...))
+            (code:line #:description description-expr)
+            (code:line #:opaque)
+            (code:line #:commit)
+            (code:line #:no-delimit-cut)
+            (code:line #:literals (literal-entry ...))
+            (code:line #:datum-literals (datum-literal-entry ...))
+            (code:line #:literal-sets (literal-set ...))
+            (code:line #:conventions (convention-id ...))
+            (code:line #:local-conventions (convention-rule ...))
+            (code:line #:disable-colon-notation)]
+           [attr-arity-decl
+            attr-name-id
+            (attr-name-id depth)]
+           [stxclass-variant
+            (pattern syntax-pattern pattern-directive ...)])
+          #:contracts ([description-expr (or/c string? #f)])]{
 
 Defines @racket[name-id] as a @deftech{syntax class}, which
 encapsulates one or more @tech{single-term patterns}.
@@ -52,9 +53,10 @@ non-empty sequence of @racket[pattern] variants.
 
 The following options are supported:
 
-@specsubform/subs[(code:line #:attributes (attr-arity-decl ...))
-                  ([attr-arity-decl attr-id
-                                    (attr-id depth)])]{
+@specsubform[(code:line #:attributes (attr-arity-decl ...))
+             #:grammar
+             ([attr-arity-decl attr-id
+                               (attr-id depth)])]{
 
 Declares the attributes of the syntax class. An attribute arity
 declaration consists of the attribute name and optionally its ellipsis
@@ -181,11 +183,12 @@ follows:
                (code:line #:when condition-expr)
                (code:line #:do [def-or-expr ...])]
 
-@specsubform/subs[(code:line #:declare pvar-id stxclass maybe-role)
-                  ([stxclass syntax-class-id
-                             (syntax-class-id arg ...)]
-                   [maybe-role (code:line)
-                               (code:line #:role role-expr)])]{
+@specsubform[(code:line #:declare pvar-id stxclass maybe-role)
+             #:grammar
+             ([stxclass syntax-class-id
+                        (syntax-class-id arg ...)]
+              [maybe-role (code:line)
+                          (code:line #:role role-expr)])]{
 
 Associates @racket[pvar-id] with a syntax class and possibly a role,
 equivalent to replacing each occurrence of @racket[pvar-id] in the