From 9e7ff2c5c4c521cf19cca9714311e768fde26c92 Mon Sep 17 00:00:00 2001 From: Matthew Flatt Date: Tue, 18 Dec 2007 01:44:09 +0000 Subject: [PATCH] doc tweaks svn: r8043 original commit: ec3f79cf47d6fa6ff4a5896756eeef683d955efa --- .../scribblings/style/scribble.scrbl | 24 ++++++++++++------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/pkgs/racket-doc/scribblings/style/scribble.scrbl b/pkgs/racket-doc/scribblings/style/scribble.scrbl index e2dee89e4c..1910ee9d2b 100644 --- a/pkgs/racket-doc/scribblings/style/scribble.scrbl +++ b/pkgs/racket-doc/scribblings/style/scribble.scrbl @@ -11,13 +11,16 @@ implicit subject is the form or value being described. Thus, the description will often start with ``Produces.'' Refer to arguments by name. -Use @schemeidfont{id} or something that ends @schemeidfont{-id} in a -syntactic form to mean an identifier, not @schemeidfont{identifier}, -@schemeidfont{name}, or @schemeidfont{symbol}. Similarly, use -@schemeidfont{expr} or something that ends @schemeidfont{-expr} for an -expression position within a syntactic form. Use @schemeidfont{body} -for a form (definition or expression) in an internal-definition -position. +Use @schemeidfont{id} or something that ends @schemeidfont{-id} in +@scheme[defform] to mean an identifier, not @schemeidfont{identifier}, +@schemeidfont{variable}, @schemeidfont{name}, or +@schemeidfont{symbol}. Similarly, use @schemeidfont{expr} or something +that ends @schemeidfont{-expr} for an expression position within a +syntactic form. Use @schemeidfont{body} for a form (definition or +expression) in an internal-definition position. Never use +@schemeidfont{expr} for something that isn't exactly an expression, +@scheme[id] for something that isn't exactly an identifier, etc.; +instead, use @scheme[defform/subs] to define a new non-terminal. Pay attention to the difference between identifiers and meta-variables when using @scheme[scheme], especially outside of @scheme[defproc] or @@ -36,8 +39,11 @@ typeset as variables. The correct description is which produces @scheme[(_rator-expr _rand-expr ...)], where @schemeidfont{rator-expr} @schemeidfont{rand-expr} are typeset as meta-variables. The @scheme[defproc], @scheme[defform], @|etc| forms -greatly reduce this burden in description, since they automatically -set up meta-variable typesetting for non-literal identifiers. +greatly reduce this burden in descriptions, since they automatically +set up meta-variable typesetting for non-literal identifiers. In +@scheme[defform], be sure to include literal identifiers (i.e., those +not meant as variables, other than the form name being defined) in a +@scheme[#:literals] clause. To typeset an identifier with no particular interpretation---syntax, variable, meta-variable, etc.---use @scheme[schemeidfont] (e.g., as in